EvoScientist 0.0.1.dev1__py3-none-any.whl → 0.0.1.dev3__py3-none-any.whl

EvoScientist/stream/state.py

@@ -0,0 +1,343 @@
+"""Stream state tracking for CLI display.
+
+Contains SubAgentState, StreamState, and todo-item parsing helpers.
+No Rich dependencies — stdlib only.
+"""
+
+import ast
+import json
+
+
+class SubAgentState:
+    """Tracks a single sub-agent's activity."""
+
+    def __init__(self, name: str, description: str = ""):
+        self.name = name
+        self.description = description
+        self.tool_calls: list[dict] = []
+        self.tool_results: list[dict] = []
+        self._result_map: dict[str, dict] = {}  # tool_call_id -> result
+        self.is_active = True
+
+    def add_tool_call(self, name: str, args: dict, tool_id: str = ""):
+        # Skip empty-name calls without an id (incomplete streaming chunks)
+        if not name and not tool_id:
+            return
+        tc_data = {"id": tool_id, "name": name, "args": args}
+        if tool_id:
+            for i, tc in enumerate(self.tool_calls):
+                if tc.get("id") == tool_id:
+                    # Merge: keep the non-empty name/args
+                    if name:
+                        self.tool_calls[i]["name"] = name
+                    if args:
+                        self.tool_calls[i]["args"] = args
+                    return
+        # Skip if name is empty and we can't deduplicate by id
+        if not name:
+            return
+        self.tool_calls.append(tc_data)
+
+    def add_tool_result(self, name: str, content: str, success: bool = True):
+        result = {"name": name, "content": content, "success": success}
+        self.tool_results.append(result)
+        # Try to match result to the first unmatched tool call with same name
+        for tc in self.tool_calls:
+            tc_id = tc.get("id", "")
+            tc_name = tc.get("name", "")
+            if tc_id and tc_id not in self._result_map and tc_name == name:
+                self._result_map[tc_id] = result
+                return
+        # Fallback: match first unmatched tool call
+        for tc in self.tool_calls:
+            tc_id = tc.get("id", "")
+            if tc_id and tc_id not in self._result_map:
+                self._result_map[tc_id] = result
+                return
+
+    def get_result_for(self, tc: dict) -> dict | None:
+        """Get matched result for a tool call."""
+        tc_id = tc.get("id", "")
+        if tc_id:
+            return self._result_map.get(tc_id)
+        # Fallback: index-based matching
+        try:
+            idx = self.tool_calls.index(tc)
+            if idx < len(self.tool_results):
+                return self.tool_results[idx]
+        except ValueError:
+            pass
+        return None
+
+
+class StreamState:
+    """Accumulates stream state for display updates."""
+
+    def __init__(self):
+        self.thinking_text = ""
+        self.response_text = ""
+        self.tool_calls = []
+        self.tool_results = []
+        self.is_thinking = False
+        self.is_responding = False
+        self.is_processing = False
+        # Sub-agent tracking
+        self.subagents: list[SubAgentState] = []
+        self._subagent_map: dict[str, SubAgentState] = {}  # name -> state
+        # Todo list tracking
+        self.todo_items: list[dict] = []
+        # Latest text segment (reset on each tool_call)
+        self.latest_text = ""
+
+    def _get_or_create_subagent(self, name: str, description: str = "") -> SubAgentState:
+        if name not in self._subagent_map:
+            # Case 1: real name arrives, "sub-agent" entry exists -> rename it
+            if name != "sub-agent" and "sub-agent" in self._subagent_map:
+                old_sa = self._subagent_map.pop("sub-agent")
+                old_sa.name = name
+                if description:
+                    old_sa.description = description
+                self._subagent_map[name] = old_sa
+                return old_sa
+            # Case 2: "sub-agent" arrives but a pre-registered real-name entry
+            #         exists with no tool calls -> merge into it
+            if name == "sub-agent":
+                active_named = [
+                    sa for sa in self.subagents
+                    if sa.is_active and sa.name != "sub-agent"
+                ]
+                if len(active_named) == 1 and not active_named[0].tool_calls:
+                    self._subagent_map[name] = active_named[0]
+                    return active_named[0]
+            sa = SubAgentState(name, description)
+            self.subagents.append(sa)
+            self._subagent_map[name] = sa
+        else:
+            existing = self._subagent_map[name]
+            if description and not existing.description:
+                existing.description = description
+            # If this entry was created as "sub-agent" placeholder and the
+            # actual name is different, update.
+            if name != "sub-agent" and existing.name == "sub-agent":
+                existing.name = name
+        return self._subagent_map[name]
+
+    def _resolve_subagent_name(self, name: str) -> str:
+        """Resolve "sub-agent" to the single active named sub-agent when possible."""
+        if name != "sub-agent":
+            return name
+        active_named = [
+            sa.name for sa in self.subagents
+            if sa.is_active and sa.name != "sub-agent"
+        ]
+        if len(active_named) == 1:
+            return active_named[0]
+        return name
+
+    def handle_event(self, event: dict) -> str:
+        """Process a single stream event, update internal state, return event type."""
+        event_type: str = event.get("type", "")
+
+        if event_type == "thinking":
+            self.is_thinking = True
+            self.is_responding = False
+            self.is_processing = False
+            self.thinking_text += event.get("content", "")
+
+        elif event_type == "text":
+            self.is_thinking = False
+            self.is_responding = True
+            self.is_processing = False
+            text_content = event.get("content", "")
+            self.response_text += text_content
+            self.latest_text += text_content
+
+        elif event_type == "tool_call":
+            self.is_thinking = False
+            self.is_responding = False
+            self.is_processing = False
+            self.latest_text = ""  # Reset -- next text segment is a new message
+
+            tool_id = event.get("id", "")
+            tool_name = event.get("name", "unknown")
+            tool_args = event.get("args", {})
+            tc_data = {
+                "id": tool_id,
+                "name": tool_name,
+                "args": tool_args,
+            }
+
+            if tool_id:
+                updated = False
+                for i, tc in enumerate(self.tool_calls):
+                    if tc.get("id") == tool_id:
+                        self.tool_calls[i] = tc_data
+                        updated = True
+                        break
+                if not updated:
+                    self.tool_calls.append(tc_data)
+            else:
+                self.tool_calls.append(tc_data)
+
+            # Capture todo items from write_todos args (most reliable source)
+            if tool_name == "write_todos":
+                todos = tool_args.get("todos", [])
+                if isinstance(todos, list) and todos:
+                    self.todo_items = todos
+
+        elif event_type == "tool_result":
+            self.is_processing = True
+            result_name = event.get("name", "unknown")
+            result_content = event.get("content", "")
+            self.tool_results.append({
+                "name": result_name,
+                "content": result_content,
+            })
+            # Update todo list from write_todos / read_todos results (fallback)
+            if result_name in ("write_todos", "read_todos"):
+                parsed = _parse_todo_items(result_content)
+                if parsed:
+                    self.todo_items = parsed
+
+        elif event_type == "subagent_start":
+            name = event.get("name", "sub-agent")
+            desc = event.get("description", "")
+            sa = self._get_or_create_subagent(name, desc)
+            sa.is_active = True
+
+        elif event_type == "subagent_tool_call":
+            sa_name = self._resolve_subagent_name(event.get("subagent", "sub-agent"))
+            sa = self._get_or_create_subagent(sa_name)
+            sa.add_tool_call(
+                event.get("name", "unknown"),
+                event.get("args", {}),
+                event.get("id", ""),
+            )
+
+        elif event_type == "subagent_tool_result":
+            sa_name = self._resolve_subagent_name(event.get("subagent", "sub-agent"))
+            sa = self._get_or_create_subagent(sa_name)
+            sa.add_tool_result(
+                event.get("name", "unknown"),
+                event.get("content", ""),
+                event.get("success", True),
+            )
+
+        elif event_type == "subagent_end":
+            name = self._resolve_subagent_name(event.get("name", "sub-agent"))
+            if name in self._subagent_map:
+                self._subagent_map[name].is_active = False
+            elif name == "sub-agent":
+                # Couldn't resolve -- deactivate the oldest active sub-agent
+                for sa in self.subagents:
+                    if sa.is_active:
+                        sa.is_active = False
+                        break
+
+        elif event_type == "done":
+            self.is_processing = False
+            if not self.response_text:
+                self.response_text = event.get("response", "")
+
+        elif event_type == "error":
+            self.is_processing = False
+            self.is_thinking = False
+            self.is_responding = False
+            error_msg = event.get("message", "Unknown error")
+            self.response_text += f"\n\n[Error] {error_msg}"
+
+        return event_type
+
+    def get_display_args(self) -> dict:
+        """Get kwargs for create_streaming_display()."""
+        return {
+            "thinking_text": self.thinking_text,
+            "response_text": self.response_text,
+            "latest_text": self.latest_text,
+            "tool_calls": self.tool_calls,
+            "tool_results": self.tool_results,
+            "is_thinking": self.is_thinking,
+            "is_responding": self.is_responding,
+            "is_processing": self.is_processing,
+            "subagents": self.subagents,
+            "todo_items": self.todo_items,
+        }
+
+
+def _parse_todo_items(content: str) -> list[dict] | None:
+    """Parse todo items from write_todos output.
+
+    Attempts to extract a list of dicts with 'status' and 'content' keys
+    from the tool result string. Returns None if parsing fails.
+
+    Handles formats like:
+      - Raw JSON/Python list: [{"content": "...", "status": "..."}]
+      - Prefixed: "Updated todo list to [{'content': '...', ...}]"
+    """
+    content = content.strip()
+
+    def _try_parse(text: str) -> list[dict] | None:
+        """Try JSON then Python literal parsing."""
+        text = text.strip()
+        try:
+            data = json.loads(text)
+            if isinstance(data, list) and data and isinstance(data[0], dict):
+                return data
+        except (json.JSONDecodeError, ValueError):
+            pass
+        try:
+            data = ast.literal_eval(text)
+            if isinstance(data, list) and data and isinstance(data[0], dict):
+                return data
+        except (ValueError, SyntaxError):
+            pass
+        return None
+
+    # Try the full content directly
+    result = _try_parse(content)
+    if result:
+        return result
+
+    # Extract embedded [...] from content (e.g. "Updated todo list to [{...}]")
+    bracket_start = content.find("[")
+    if bracket_start != -1:
+        bracket_end = content.rfind("]")
+        if bracket_end > bracket_start:
+            embedded = content[bracket_start:bracket_end + 1]
+            result = _try_parse(embedded)
+            if result:
+                return result
+
+    # Try line-by-line scan
+    for line in content.split("\n"):
+        line = line.strip()
+        if "[" in line:
+            start = line.find("[")
+            end = line.rfind("]")
+            if end > start:
+                result = _try_parse(line[start:end + 1])
+                if result:
+                    return result
+
+    return None
+
+
+def _build_todo_stats(items: list[dict]) -> str:
+    """Build stats string like '2 active | 1 pending | 3 done'."""
+    counts: dict[str, int] = {}
+    for item in items:
+        status = str(item.get("status", "todo")).lower()
+        # Normalize status names
+        if status in ("done", "completed", "complete"):
+            status = "done"
+        elif status in ("active", "in_progress", "in-progress", "working"):
+            status = "active"
+        else:
+            status = "pending"
+        counts[status] = counts.get(status, 0) + 1
+
+    parts = []
+    for key in ("active", "pending", "done"):
+        if counts.get(key, 0) > 0:
+            parts.append(f"{counts[key]} {key}")
+    return " | ".join(parts) if parts else f"{len(items)} items"

EvoScientist/stream/utils.py

@@ -114,34 +114,40 @@ def format_tool_compact(name: str, args: dict | None) -> str:
     if name_lower == "execute":
         cmd = args.get("command", "")
         if len(cmd) > 50:
-            cmd = cmd[:47] + "..."
+            cmd = cmd[:47] + "\u2026"
         return f"execute({cmd})"
 
-    # File operations
+    # File operations (with special case for memory files)
     if name_lower == "read_file":
-        path = _shorten_path(args.get("path", ""))
-        return f"read_file({path})"
+        path = args.get("path", "")
+        if path.endswith("/MEMORY.md") or path == "/MEMORY.md":
+            return "Reading memory"
+        return f"read_file({_shorten_path(path)})"
 
     if name_lower == "write_file":
-        path = _shorten_path(args.get("path", ""))
-        return f"write_file({path})"
+        path = args.get("path", "")
+        if path.endswith("/MEMORY.md") or path == "/MEMORY.md":
+            return "Updating memory"
+        return f"write_file({_shorten_path(path)})"
 
     if name_lower == "edit_file":
-        path = _shorten_path(args.get("path", ""))
-        return f"edit_file({path})"
+        path = args.get("path", "")
+        if path.endswith("/MEMORY.md") or path == "/MEMORY.md":
+            return "Updating memory"
+        return f"edit_file({_shorten_path(path)})"
 
     # Search operations
     if name_lower == "glob":
         pattern = args.get("pattern", "")
         if len(pattern) > 40:
-            pattern = pattern[:37] + "..."
+            pattern = pattern[:37] + "\u2026"
         return f"glob({pattern})"
 
     if name_lower == "grep":
         pattern = args.get("pattern", "")
         path = args.get("path", ".")
         if len(pattern) > 30:
-            pattern = pattern[:27] + "..."
+            pattern = pattern[:27] + "\u2026"
         return f"grep({pattern}, {path})"
 
     # Directory listing
@@ -163,16 +169,17 @@ def format_tool_compact(name: str, args: dict | None) -> str:
     if name_lower == "task":
         sa_type = args.get("subagent_type", "").strip()
         task_desc = args.get("description", args.get("task", "")).strip()
+        task_desc = task_desc.split("\n")[0].strip() if task_desc else ""
         if sa_type:
             if task_desc:
                 if len(task_desc) > 50:
-                    task_desc = task_desc[:47] + "..."
+                    task_desc = task_desc[:47] + "\u2026"
                 return f"Cooking with {sa_type} — {task_desc}"
             return f"Cooking with {sa_type}"
         # Fallback if no subagent_type
         if task_desc:
             if len(task_desc) > 50:
-                task_desc = task_desc[:47] + "..."
+                task_desc = task_desc[:47] + "\u2026"
             return f"Cooking with sub-agent — {task_desc}"
         return "Cooking with sub-agent"
 
@@ -185,14 +192,14 @@ def format_tool_compact(name: str, args: dict | None) -> str:
     if name_lower in ("tavily_search", "internet_search"):
         query = args.get("query", "")
         if len(query) > 40:
-            query = query[:37] + "..."
+            query = query[:37] + "\u2026"
         return f"{name}({query})"
 
     # Think/reflection
     if name_lower == "think_tool":
         reflection = args.get("reflection", "")
         if len(reflection) > 40:
-            reflection = reflection[:37] + "..."
+            reflection = reflection[:37] + "\u2026"
         return f"think_tool({reflection})"
 
     # Default: show first few params
@@ -200,12 +207,12 @@ def format_tool_compact(name: str, args: dict | None) -> str:
     for k, v in list(args.items())[:2]:
         v_str = str(v)
         if len(v_str) > 20:
-            v_str = v_str[:17] + "..."
+            v_str = v_str[:17] + "\u2026"
         params.append(f"{k}={v_str}")
 
     params_str = ", ".join(params)
     if len(params_str) > 50:
-        params_str = params_str[:47] + "..."
+        params_str = params_str[:47] + "\u2026"
 
     return f"{name}({params_str})"
 

EvoScientist/tools.py

@@ -106,6 +106,70 @@ async def tavily_search(
         return f"Search failed: {str(e)}"
 
 
+@tool(parse_docstring=True)
+def skill_manager(
+    action: Literal["install", "list", "uninstall"],
+    source: str = "",
+    name: str = "",
+) -> str:
+    """Manage user skills: install, list, or uninstall.
+
+    Use this tool when the user asks to:
+    - Install a skill (action="install", source required)
+    - List installed skills (action="list")
+    - Uninstall a skill (action="uninstall", name required)
+
+    Supported sources for install:
+    - Local path: "./my-skill" or "/path/to/skill"
+    - GitHub URL: "https://github.com/owner/repo/tree/main/skill-name"
+    - GitHub shorthand: "owner/repo@skill-name"
+
+    Args:
+        action: One of "install", "list", or "uninstall"
+        source: For install - local path or GitHub URL/shorthand
+        name: For uninstall - skill name to remove
+
+    Returns:
+        Result message
+    """
+    from .skills_manager import install_skill, list_skills, uninstall_skill
+
+    if action == "install":
+        if not source:
+            return "Error: 'source' is required for install action"
+        result = install_skill(source)
+        if result["success"]:
+            return (
+                f"Successfully installed skill: {result['name']}\n"
+                f"Description: {result.get('description', '(none)')}\n"
+                f"Path: {result['path']}\n\n"
+                f"Use load_skill to activate it."
+            )
+        else:
+            return f"Failed to install skill: {result['error']}"
+
+    elif action == "list":
+        skills = list_skills(include_system=False)
+        if not skills:
+            return "No user skills installed. Use action='install' to add skills."
+        lines = [f"Installed User Skills ({len(skills)}):"]
+        for skill in skills:
+            lines.append(f"  - {skill.name}: {skill.description}")
+        return "\n".join(lines)
+
+    elif action == "uninstall":
+        if not name:
+            return "Error: 'name' is required for uninstall action"
+        result = uninstall_skill(name)
+        if result["success"]:
+            return f"Successfully uninstalled skill: {name}"
+        else:
+            return f"Failed to uninstall skill: {result['error']}"
+
+    else:
+        return f"Unknown action: {action}. Use 'install', 'list', or 'uninstall'."
+
+
 @tool(parse_docstring=True)
 def think_tool(reflection: str) -> str:
     """Tool for strategic reflection on research progress and decision-making.

{evoscientist-0.0.1.dev1.dist-info → evoscientist-0.0.1.dev3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: EvoScientist
-Version: 0.0.1.dev1
+Version: 0.0.1.dev3
 Summary: EvoScientist: Towards Self-Evolving AI Scientists for End-to-End Scientific Discovery
 Author: Xi Zhang
 Maintainer: Xi Zhang
@@ -21,6 +21,7 @@ Requires-Dist: tavily-python>=0.7
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=14.0
 Requires-Dist: prompt-toolkit>=3.0
+Requires-Dist: typer>=0.12
 Requires-Dist: python-dotenv>=1.0
 Requires-Dist: langgraph-cli[inmem]>=0.4
 Requires-Dist: httpx>=0.27
@@ -41,11 +42,12 @@ Dynamic: license-file
 
 <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>
 
-[![Project Page](https://img.shields.io/badge/Project-Page-4285F4?style=for-the-badge&logo=googlelens&logoColor=4285F4)]()
+[![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)]()
-[![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)]()
 [![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>
 
@@ -60,6 +62,7 @@ Dynamic: license-file
 
 ## 📖 Contents
 - [⛏️ Installation](#️-installation)
+- [🔑 API Key Configuration](#-api-key-configuration)
 - [⚡ Quick Start](#-quick-start)
   - [CLI Inference](#cli-inference)
   - [Script Inference](#script-inference)
@@ -105,6 +108,42 @@ uv pip install -e .
 
 </details>
 
+## 🔑 API Key Configuration
+
+EvoScientist requires API keys for LLM inference and web search. You can configure them in two ways:
+
+### Option A: Environment Variables (Global)
+
+Set keys directly in your terminal session. Add these to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.) to persist across sessions:
+
+```Shell
+export ANTHROPIC_API_KEY="your_anthropic_api_key_here"
+export TAVILY_API_KEY="your_tavily_api_key_here"
+```
+
+### Option B: `.env` File (Project-level)
+
+Create a `.env` file in the project root. This keeps keys scoped to the project and out of your shell history:
+
+```Shell
+cp .env.example .env
+```
+
+Then edit `.env` and fill in your keys:
+
+```
+ANTHROPIC_API_KEY=your_anthropic_api_key_here
+TAVILY_API_KEY=your_tavily_api_key_here
+```
+
+> [!WARNING]
+> Never commit `.env` files containing real API keys to version control. The `.env` file is already included in `.gitignore`.
+
+| Key | Required | Description |
+|-----|----------|-------------|
+| `ANTHROPIC_API_KEY` | Yes | Anthropic API key for Claude ([console.anthropic.com](https://console.anthropic.com/)) |
+| `TAVILY_API_KEY` | Yes | Tavily API key for web search ([app.tavily.com](https://app.tavily.com/)) |
+
 ## ⚡ Quick Start
 
 ### CLI Inference  
@@ -113,11 +152,71 @@ You can perform inference directly from the command line using our CLI tool:
 ![demo](./assets/EvoScientist_cli.png)
 
 ```Shell
-python -m EvoScientist
+python -m EvoScientist 
 ```
-**Optional arguments:**  
+or
+```Shell
+EvoSci # or EvoScientist
+```
+**Optional arguments:**
 
-> TODO
+```
+--workdir <path>   Override workspace directory for this session
+--use-cwd          Use current working directory as workspace
+--thread-id <id>   Resume a conversation thread
+--no-thinking      Disable thinking display
+```
+
+**Interactive Commands:**
+
+| Command | Description |
+|---------|-------------|
+| `/exit` | Quit the session |
+| `/new` | Start a new session (new workspace + thread) |
+| `/thread` | Show current thread ID and workspace path |
+| `/skills` | List installed user skills |
+| `/install-skill <source>` | Install a skill from local path or GitHub |
+| `/uninstall-skill <name>` | Uninstall a user-installed skill |
+
+**Skill Installation Examples:**
+
+```bash
+# Install from local path
+/install-skill ./my-skill
+
+# Install from GitHub URL
+/install-skill https://github.com/owner/repo/tree/main/skill-name
+
+# Install from GitHub shorthand
+/install-skill owner/repo@skill-name
+```
+
+### Runtime Directories
+
+By default, the **workspace** is created under a hidden directory in the current
+project directory:
+
+```
+./.evoscientist/workspace/
+  memory/   # shared MEMORY.md
+  skills/   # user-installed skills
+  runs/     # per-thread workspaces
+```
+
+You can force workspace to be the current directory via `--use-cwd`.
+
+If you set `EVOSCIENTIST_HOME`, EvoScientist will place `workspace/` under that
+directory instead of the project root:
+
+Example with `EVOSCIENTIST_HOME=~/.evoscientist`:
+
+```
+~/.evoscientist/
+  workspace/
+    memory/
+    skills/
+    runs/
+```
 
 ### Script Inference
 ```python