EvoScientist 0.0.1.dev2__py3-none-any.whl

EvoScientist/tools.py

@@ -0,0 +1,135 @@
+"""Tools.
+
+This module provides search and reflection tools for the research agent,
+using Tavily for URL discovery and fetching full webpage content.
+"""
+
+import asyncio
+from typing import Literal
+
+import httpx
+from dotenv import load_dotenv
+from langchain_core.tools import InjectedToolArg, tool
+from markdownify import markdownify
+from tavily import TavilyClient
+from typing_extensions import Annotated
+
+load_dotenv(override=True)
+
+tavily_client = TavilyClient()
+
+
+async def fetch_webpage_content(url: str, timeout: float = 10.0) -> str:
+    """Fetch and convert webpage content to markdown.
+
+    Args:
+        url: URL to fetch
+        timeout: Request timeout in seconds
+
+    Returns:
+        Webpage content as markdown
+    """
+    headers = {
+        "User-Agent": (
+            "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+            "AppleWebKit/537.36 (KHTML, like Gecko) "
+            "Chrome/91.0.4472.124 Safari/537.36"
+        )
+    }
+
+    try:
+        async with httpx.AsyncClient() as client:
+            response = await client.get(url, headers=headers, timeout=timeout)
+            response.raise_for_status()
+            return markdownify(response.text)
+    except Exception as e:
+        return f"Error fetching content from {url}: {str(e)}"
+
+
+@tool(parse_docstring=True)
+async def tavily_search(
+    query: str,
+    max_results: Annotated[int, InjectedToolArg] = 3,
+    topic: Annotated[
+        Literal["general", "news", "finance"], InjectedToolArg
+    ] = "general",
+) -> str:
+    """Search the web for information on a given query.
+
+    Uses Tavily to discover relevant URLs, then fetches and returns
+    full webpage content as markdown for comprehensive research.
+
+    Args:
+        query: Search query to execute
+
+    Returns:
+        Formatted search results with full webpage content in markdown
+    """
+
+    def _sync_search() -> dict:
+        return tavily_client.search(
+            query,
+            max_results=max_results,
+            topic=topic,
+        )
+
+    try:
+        # Run Tavily search asynchronously
+        search_results = await asyncio.to_thread(_sync_search)
+
+        # Fetch full content for each URL concurrently
+        results = search_results.get("results", [])
+        if not results:
+            return f"No results found for '{query}'"
+
+        # Fetch all webpages concurrently
+        fetch_tasks = [fetch_webpage_content(r["url"]) for r in results]
+        contents = await asyncio.gather(*fetch_tasks)
+
+        # Format results
+        result_texts = []
+        for result, content in zip(results, contents):
+            result_text = f"""## {result["title"]}
+**URL:** {result["url"]}
+
+{content}
+
+---
+"""
+            result_texts.append(result_text)
+
+        return f"""Found {len(result_texts)} result(s) for '{query}':
+
+{"".join(result_texts)}"""
+
+    except Exception as e:
+        return f"Search failed: {str(e)}"
+
+
+@tool(parse_docstring=True)
+def think_tool(reflection: str) -> str:
+    """Tool for strategic reflection on research progress and decision-making.
+
+    Use this tool after each search to analyze results and plan next steps systematically.
+    This creates a deliberate pause in the research workflow for quality decision-making.
+
+    When to use:
+    - After receiving search results: What key information did I find?
+    - Before deciding next steps: Do I have enough to answer comprehensively?
+    - When assessing research gaps: What specific information am I still missing?
+    - Before concluding research: Can I provide a complete answer now?
+
+    Reflection should address:
+    1. Analysis of current findings - What concrete information have I gathered?
+    2. Gap assessment - What crucial information is still missing?
+    3. Quality evaluation - Do I have sufficient evidence/examples for a good answer?
+    4. Strategic decision - Should I continue searching or provide my answer?
+    5. Skill leverage - Is there a relevant local skill to load that can accelerate this work?
+
+    Args:
+        reflection: Your detailed reflection on research progress, findings, gaps, and next steps
+
+    Returns:
+        Confirmation that reflection was recorded for decision-making
+    """
+    return f"Reflection recorded: {reflection}"

EvoScientist/utils.py

@@ -0,0 +1,207 @@
+"""Utility functions for EvoScientist.
+
+This module primarily contains helpers for displaying messages and prompts in
+notebooks, and lightweight configuration loaders used by the agent runtime.
+"""
+
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+
+console = Console()
+
+
+def format_message_content(message):
+    """Convert message content to displayable string."""
+    parts = []
+    tool_calls_processed = False
+
+    # Handle main content
+    if isinstance(message.content, str):
+        parts.append(message.content)
+    elif isinstance(message.content, list):
+        # Handle complex content like tool calls (Anthropic format)
+        for item in message.content:
+            if item.get("type") == "text":
+                parts.append(item["text"])
+            elif item.get("type") == "tool_use":
+                parts.append(f"\n🔧 Tool Call: {item['name']}")
+                parts.append(f"   Args: {json.dumps(item['input'], indent=2)}")
+                parts.append(f"   ID: {item.get('id', 'N/A')}")
+                tool_calls_processed = True
+    else:
+        parts.append(str(message.content))
+
+    # Handle tool calls attached to the message (OpenAI format) - only if not already processed
+    if (
+        not tool_calls_processed
+        and hasattr(message, "tool_calls")
+        and message.tool_calls
+    ):
+        for tool_call in message.tool_calls:
+            parts.append(f"\n🔧 Tool Call: {tool_call['name']}")
+            parts.append(f"   Args: {json.dumps(tool_call['args'], indent=2)}")
+            parts.append(f"   ID: {tool_call['id']}")
+
+    return "\n".join(parts)
+
+
+def format_messages(messages):
+    """Format and display a list of messages with Rich formatting."""
+    for m in messages:
+        msg_type = m.__class__.__name__.replace("Message", "")
+        content = format_message_content(m)
+
+        if msg_type == "Human":
+            console.print(Panel(content, title="🧑 Human", border_style="blue"))
+        elif msg_type == "Ai":
+            console.print(Panel(content, title="🤖 Assistant", border_style="green"))
+        elif msg_type == "Tool":
+            console.print(Panel(content, title="🔧 Tool Output", border_style="yellow"))
+        else:
+            console.print(Panel(content, title=f"📝 {msg_type}", border_style="white"))
+
+
+def format_message(messages):
+    """Alias for format_messages for backward compatibility."""
+    return format_messages(messages)
+
+
+def show_prompt(prompt_text: str, title: str = "Prompt", border_style: str = "blue"):
+    """Display a prompt with rich formatting and XML tag highlighting.
+
+    Args:
+        prompt_text: The prompt string to display
+        title: Title for the panel (default: "Prompt")
+        border_style: Border color style (default: "blue")
+    """
+    # Create a formatted display of the prompt
+    formatted_text = Text(prompt_text)
+    formatted_text.highlight_regex(r"<[^>]+>", style="bold blue")  # Highlight XML tags
+    formatted_text.highlight_regex(
+        r"##[^#\n]+", style="bold magenta"
+    )  # Highlight headers
+    formatted_text.highlight_regex(
+        r"###[^#\n]+", style="bold cyan"
+    )  # Highlight sub-headers
+
+    # Display in a panel for better presentation
+    console.print(
+        Panel(
+            formatted_text,
+            title=f"[bold green]{title}[/bold green]",
+            border_style=border_style,
+            padding=(1, 2),
+        )
+    )
+
+
+def load_subagents(
+    config_path: Path,
+    *,
+    tool_registry: dict[str, Any],
+    prompt_refs: dict[str, str] | None = None,
+) -> list[dict[str, Any]]:
+    """Load subagent definitions from YAML and wire up tools.
+
+    NOTE: This is a custom utility. deepagents does not natively load subagents
+    from files - they're normally defined inline in the create_deep_agent() call.
+    We externalize to YAML here to keep configuration separate from code.
+
+    Supported YAML schemas:
+
+    1) Mapping style (recommended):
+       planner-agent:
+         description: "..."
+         tools: [think_tool]
+         system_prompt: |
+           ...
+       research-agent:
+         description: "..."
+         tools: [tavily_search, think_tool]
+         system_prompt_ref: RESEARCHER_INSTRUCTIONS
+
+    2) List style (legacy):
+       subagents:
+         - name: planner-agent
+           description: "..."
+           tools: [think_tool]
+           system_prompt: |
+             ...
+    """
+    prompt_refs = prompt_refs or {}
+
+    with config_path.open(encoding="utf-8") as f:
+        config = yaml.safe_load(f) or {}
+
+    if not isinstance(config, dict) or not config:
+        raise ValueError("subagent.yaml must be a mapping or contain 'subagents:'")
+
+    subagents: list[dict[str, Any]] = []
+
+    def _build_one(name: str, spec: dict[str, Any]) -> dict[str, Any]:
+        subagent: dict[str, Any] = {
+            "name": name,
+            "description": spec.get("description", ""),
+        }
+
+        if "system_prompt_ref" in spec:
+            ref = spec["system_prompt_ref"]
+            if ref not in prompt_refs:
+                raise ValueError(f"Unknown system_prompt_ref '{ref}' for subagent '{name}'")
+            subagent["system_prompt"] = prompt_refs[ref]
+        else:
+            subagent["system_prompt"] = spec.get("system_prompt", "")
+
+        if "model" in spec:
+            subagent["model"] = spec["model"]
+
+        if "tools" in spec:
+            subagent["tools"] = [tool_registry[t] for t in spec["tools"]]
+
+        return subagent
+
+    # Legacy list style
+    if "subagents" in config:
+        items = config.get("subagents")
+        if not isinstance(items, list) or not items:
+            raise ValueError("subagent.yaml must contain a non-empty 'subagents:' list")
+        for item in items:
+            if not isinstance(item, dict):
+                continue
+            name = item.get("name")
+            if not name:
+                raise ValueError("Each subagent entry must have a 'name'")
+            subagents.append(_build_one(name, item))
+        return subagents
+
+    # Mapping style: {<name>: <spec>}
+    for name, spec in config.items():
+        if not isinstance(spec, dict):
+            continue
+        subagents.append(_build_one(name, spec))
+
+    return subagents
+
+
+def load_subagent(
+    config_path: Path,
+    name: str,
+    *,
+    tool_registry: dict[str, Any],
+    prompt_refs: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    """Load a single sub-agent by name from YAML."""
+    for agent in load_subagents(
+        config_path,
+        tool_registry=tool_registry,
+        prompt_refs=prompt_refs,
+    ):
+        if agent.get("name") == name:
+            return agent
+    raise KeyError(f"Sub-agent not found: {name}")

evoscientist-0.0.1.dev2.dist-info/METADATA

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: EvoScientist
+Version: 0.0.1.dev2
+Summary: EvoScientist: Towards Self-Evolving AI Scientists for End-to-End Scientific Discovery
+Author: Xi Zhang
+Maintainer: Xi Zhang
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/EvoScientist/EvoScientist
+Project-URL: Bug Tracker, https://github.com/EvoScientist/EvoScientist/issues
+Project-URL: Documentation, https://github.com/EvoScientist/EvoScientist#readme
+Keywords: ai-scientific,scientific-discovery,self-evolving,ai-scientists,end-to-end
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: deepagents>=0.3.6
+Requires-Dist: langchain>=1.2
+Requires-Dist: langchain-anthropic>=1.3
+Requires-Dist: anthropic>=0.76
+Requires-Dist: tavily-python>=0.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=14.0
+Requires-Dist: prompt-toolkit>=3.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: langgraph-cli[inmem]>=0.4
+Requires-Dist: httpx>=0.27
+Requires-Dist: markdownify>=0.14
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Dynamic: license-file
+
+<!-- Add logo here -->
+<h1 align="center">
+  <!-- <img src="./assets/CCD_icon_logo.png" alt="CCD Logo" height="27" style="position: relative; top: -2px;"/> -->
+  <strong>EvoScientist</strong>
+</h1>
+
+
+<div align="center">
+
+<a href="https://git.io/typing-svg"><img src="https://readme-typing-svg.demolab.com?font=Fira+Code&pause=1000&width=435&lines=Towards+Self-Evolving+AI+Scientists+for+End-to-End+Scientific+Discovery" alt="Typing SVG" /></a>
+
+[![PyPI](https://img.shields.io/badge/PyPI-EvoScientist%20v0.0.1-3da9fc?style=for-the-badge&logo=python&logoColor=3da9fc)](https://pypi.org/project/EvoScientist/)
+[![Project Page](https://img.shields.io/badge/Project-Page-ff8e3c?style=for-the-badge&logo=googlelens&logoColor=ff8e3c)]()
+[![arXiv](https://img.shields.io/badge/arXiv-xxxx.xxxx-b31b1b?style=for-the-badge&logo=arxiv&logoColor=b31b1b)]()
+[![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)]()
+<!-- [![Gradio Demo](https://img.shields.io/badge/Gradio-Online_Demo-FFCC00?style=for-the-badge&logo=gradio&logoColor=yellow&labelColor=grey)]()
+[![Evaluation Split](https://img.shields.io/badge/HF-Test_Dataset-AECBFA?style=for-the-badge&logo=huggingface&logoColor=FFCC00&labelColor=grey)]() -->
+
+</div>
+
+## 🔥 News
+> TODO
+- **[27 Sep 2025]** ⛳ Our preprint is now live on [arXiv] — check it out for details.
+
+
+## Overview
+> TODO
+
+
+## 📖 Contents
+- [⛏️ Installation](#️-installation)
+- [⚡ Quick Start](#-quick-start)
+  - [CLI Inference](#cli-inference)
+  - [Script Inference](#script-inference)
+  - [Web Interface](#web-interface)
+- [📊 Evaluation](#-evaluation)
+- [📝 Citation](#-citation)
+- [📚 Acknowledgments](#-acknowledgments)
+- [📦 Codebase Contributors](#-codebase-contributors)
+- [📜 License](#-license)
+
+## ⛏️ Installation
+
+> [!TIP]  
+> Use [`uv`](https://pypi.org/project/uv) for installation — it's faster and more reliable than `pip`.
+### For Development
+
+```Shell
+# Create and activate a conda environment
+conda create -n EvoSci python=3.11 -y
+conda activate EvoSci
+
+# Install in development (editable) mode
+pip install EvoScientist
+# or
+pip install -e .
+```
+
+### Option 1:
+Install the latest version directly from GitHub for quick setup:
+> TODO
+### Option 2: 
+If you plan to modify the code or contribute to the project, you can clone the repository and install it in editable mode:
+
+> TODO
+
+<details>
+<summary> 🔄 Upgrade to the latest code base </summary>
+
+```Shell
+git pull
+uv pip install -e .
+```
+
+</details>
+
+## ⚡ Quick Start
+
+### CLI Inference  
+You can perform inference directly from the command line using our CLI tool:
+
+![demo](./assets/EvoScientist_cli.png)
+
+```Shell
+python -m EvoScientist 
+```
+or
+```Shell
+EvoSci # or EvoScientist
+```
+**Optional arguments:**  
+
+> TODO
+
+### Script Inference
+```python
+from EvoScientist import EvoScientist_agent
+from langchain_core.messages import HumanMessage
+from EvoScientist.utils import format_messages
+
+thread = {"configurable": {"thread_id": "1"}}
+question = "Hi?"
+last_len = 0
+
+for state in EvoScientist_agent.stream(
+    {"messages": [HumanMessage(content=question)]},
+    config=thread,
+    stream_mode="values",
+):
+    msgs = state["messages"]
+    if len(msgs) > last_len:
+        format_messages(msgs[last_len:]) 
+        last_len = len(msgs)
+```
+
+<details>
+<summary> Output </summary>
+
+```json
+
+╭─────────────────────────────────────────────────── 🧑 Human ────────────────────────────────────────────────────╮
+│ Hi?                                                                                                             │
+╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+╭───────────────────────────────────────────────────── 📝 AI ─────────────────────────────────────────────────────╮
+│ Hi! I'm here to help you with experimental research tasks. I can assist with:                                   │
+│                                                                                                                 │
+│ - **Planning experiments** - designing stages, success criteria, and workflows                                  │
+│ - **Running experiments** - implementing baselines, training models, analyzing results                          │
+│ - **Research** - finding papers, methods, datasets, and baselines                                               │
+│ - **Analysis** - computing metrics, creating visualizations, interpreting results                               │
+│ - **Writing** - drafting experimental reports and documentation                                                 │
+│                                                                                                                 │
+│ What would you like to work on today?                                                                           │
+╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+```
+
+</details>
+
+### Web Interface  
+
+> TODO
+
+
+## 📊 Evaluation  
+
+> TODO
+
+## 📝 Citation
+
+If you find our paper and code useful in your research and applications, please cite using this BibTeX:
+
+> TODO
+
+## 📚 Acknowledgments
+
+This project builds upon the following outstanding open-source works:
+
+- [**Deep Agents**](https://github.com/langchain-ai/deepagents) — A framework for building AI agents that can interact with various tools and environments.
+- [**Deep Agents UI**](https://github.com/langchain-ai/deep-agents-ui) — A user interface for visualising and managing Deep Agents.
+
+We thank the authors for their valuable contributions to the open-source community.
+
+
+## 📦 Codebase Contributors
+
+<table>
+  <tbody>
+    <tr>
+      <td align="center">
+        <a href="https://youganglyu.github.io/">
+          <img src="https://youganglyu.github.io/images/profile.png"
+               width="100" height="100"
+               style="object-fit: cover; border-radius: 20%;" alt="Yougang Lyu"/>
+          <br />
+          <sub><b>Yougang Lyu</b></sub>
+        </a>
+      </td>
+      <td align="center">
+        <a href="https://x-izhang.github.io/">
+          <img src="https://x-izhang.github.io/author/xi-zhang/avatar_hu13660783057866068725.jpg"
+               width="100" height="100"
+               style="object-fit: cover; border-radius: 20%;" alt="Xi Zhang"/>
+          <br />
+          <sub><b>Xi Zhang</b></sub>
+        </a>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+For any enquiries or collaboration opportunities, please contact: [**youganglyu@gmail.com**](mailto:youganglyu@gmail.com)
+
+## 📜 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.