vibecore 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

vibecore/tools/websearch/executor.py

@@ -0,0 +1,43 @@
+"""Websearch execution logic with backend selection."""
+
+from .base import WebSearchBackend
+from .ddgs import DDGSBackend
+from .models import SearchParams
+
+# Default backend
+_default_backend: WebSearchBackend = DDGSBackend()
+
+
+def set_default_backend(backend: WebSearchBackend) -> None:
+    """Set the default search backend.
+
+    Args:
+        backend: The backend to use for searches
+    """
+    global _default_backend
+    _default_backend = backend
+
+
+def get_default_backend() -> WebSearchBackend:
+    """Get the current default search backend.
+
+    Returns:
+        The current default backend
+    """
+    return _default_backend
+
+
+async def perform_websearch(params: SearchParams, backend: WebSearchBackend | None = None) -> str:
+    """Perform a web search using the specified or default backend.
+
+    Args:
+        params: Search parameters
+        backend: Optional specific backend to use (defaults to default backend)
+
+    Returns:
+        JSON string containing search results or error message
+    """
+    if backend is None:
+        backend = _default_backend
+
+    return await backend.search(params)

vibecore/tools/websearch/models.py

@@ -0,0 +1,20 @@
+"""Models for websearch tool."""
+
+from pydantic import BaseModel, Field
+
+
+class SearchResult(BaseModel):
+    """A single search result."""
+
+    title: str = Field(description="Title of the search result")
+    href: str = Field(description="URL of the search result")
+    body: str = Field(description="Description/snippet of the result")
+
+
+class SearchParams(BaseModel):
+    """Parameters for web search."""
+
+    query: str = Field(description="Search query")
+    max_results: int = Field(default=5, description="Maximum number of results to return")
+    region: str | None = Field(default=None, description="Region code (e.g., 'us-en')")
+    safesearch: str = Field(default="moderate", description="SafeSearch setting: 'on', 'moderate', or 'off'")

vibecore/tools/websearch/tools.py

@@ -0,0 +1,49 @@
+"""Websearch tool for Vibecore agents."""
+
+from agents import RunContextWrapper, function_tool
+
+from vibecore.context import VibecoreContext
+
+from .executor import perform_websearch
+from .models import SearchParams
+
+
+@function_tool
+async def websearch(
+    ctx: RunContextWrapper[VibecoreContext],
+    query: str,
+    max_results: int = 5,
+    region: str | None = None,
+    safesearch: str = "moderate",
+) -> str:
+    """Search the web for information using DuckDuckGo.
+
+    This tool allows you to search the web for current information, news, and general knowledge.
+    It supports advanced search operators like quotes for exact phrases, minus for exclusions,
+    site: for specific domains, and filetype: for specific file types.
+
+    Args:
+        ctx: The run context wrapper
+        query: The search query (supports advanced operators like "exact phrase", -exclude, site:example.com)
+        max_results: Maximum number of results to return (default: 5)
+        region: Optional region code for localized results (e.g., 'us-en' for US English)
+        safesearch: SafeSearch filter level ('on', 'moderate', or 'off', default: 'moderate')
+
+    Returns:
+        JSON string containing search results with title, URL, and snippet for each result
+
+    Examples:
+        - Basic search: query="python programming"
+        - Exact phrase: query='"machine learning algorithms"'
+        - Exclude terms: query="python -javascript"
+        - Site-specific: query="AI site:github.com"
+        - File type: query="climate change filetype:pdf"
+    """
+    params = SearchParams(
+        query=query,
+        max_results=max_results,
+        region=region,
+        safesearch=safesearch,
+    )
+
+    return await perform_websearch(params)

vibecore/widgets/tool_message_factory.py

@@ -9,15 +9,19 @@ import contextlib
 import json
 from typing import Any
 
+from vibecore.settings import settings
 from vibecore.widgets.messages import MessageStatus
 from vibecore.widgets.tool_messages import (
     BaseToolMessage,
     MCPToolMessage,
     PythonToolMessage,
     ReadToolMessage,
+    RichToolMessage,
     TaskToolMessage,
     TodoWriteToolMessage,
     ToolMessage,
+    WebFetchToolMessage,
+    WebSearchToolMessage,
     WriteToolMessage,
 )
 
@@ -113,6 +117,26 @@ def create_tool_message(
         else:
             return WriteToolMessage(file_path=file_path, content=content, status=status)
 
+    elif tool_name == "websearch":
+        query = args_dict.get("query", "") if args_dict else ""
+        if output is not None:
+            return WebSearchToolMessage(query=query, output=output, status=status)
+        else:
+            return WebSearchToolMessage(query=query, status=status)
+
+    elif tool_name == "webfetch":
+        url = args_dict.get("url", "") if args_dict else ""
+        if output is not None:
+            return WebFetchToolMessage(url=url, output=output, status=status)
+        else:
+            return WebFetchToolMessage(url=url, status=status)
+
+    elif tool_name in settings.rich_tool_names:
+        if output is not None:
+            return RichToolMessage(tool_name=tool_name, arguments=arguments, output=output, status=status)
+        else:
+            return RichToolMessage(tool_name=tool_name, arguments=arguments, status=status)
+
     # Default to generic ToolMessage for all other tools
     else:
         if output is not None:

vibecore/widgets/tool_messages.py

@@ -481,3 +481,222 @@ class MCPToolMessage(BaseToolMessage):
                         yield ExpandableMarkdown(
                             processed_output, language="", truncated_lines=5, classes="mcp-output-markdown"
                         )
+
+
+class RichToolMessage(BaseToolMessage):
+    """A widget to display rich (json/markdown) custom tool execution messages."""
+
+    tool_name: reactive[str] = reactive("")
+    arguments: reactive[str] = reactive("")
+
+    def __init__(
+        self,
+        tool_name: str,
+        arguments: str,
+        output: str = "",
+        status: MessageStatus = MessageStatus.EXECUTING,
+        **kwargs,
+    ) -> None:
+        """
+        Construct an RichToolMessage.
+
+        Args:
+            tool_name: The name of the tool being called.
+            arguments: JSON string of tool arguments.
+            output: The output from the tool (optional, can be set later).
+            status: The status of execution.
+            **kwargs: Additional keyword arguments for Widget.
+        """
+        super().__init__(status=status, **kwargs)
+        self.tool_name = tool_name
+        self.arguments = arguments
+        self.output = output
+
+    def _prettify_json_output(self, output: str) -> tuple[bool, str]:
+        """Try to prettify JSON output.
+
+        Args:
+            output: The raw output string.
+
+        Returns:
+            A tuple of (is_json, formatted_output).
+        """
+        if not output or not output.strip():
+            return False, output
+
+        try:
+            # Try to parse as JSON
+            json_obj = json.loads(output)
+            # Pretty print with 2-space indentation
+            formatted = json.dumps(json_obj, indent=2, ensure_ascii=False)
+            return True, formatted
+        except (json.JSONDecodeError, TypeError, ValueError):
+            # Not valid JSON, return as-is
+            return False, output
+
+    def compose(self) -> ComposeResult:
+        """Create child widgets for the rich tool message."""
+        # Header line showing MCP server and tool
+        # Access the actual values, not the reactive descriptors
+        yield MessageHeader("⏺", self.tool_name, status=self.status)
+
+        # Arguments display (if any)
+        if self.arguments and self.arguments != "{}":
+            with Horizontal(classes="rich-arguments"):
+                yield Static("└─", classes="rich-arguments-prefix")
+                with Vertical(classes="rich-arguments-content"):
+                    # Truncate arguments if too long
+                    max_args_length = 100
+                    arg_dict = json.loads(self.arguments)
+                    SQL_QUERY_KEY = "query"
+                    if SQL_QUERY_KEY in arg_dict:
+                        # XXX(serialx): Special case for SQL queries
+                        query = arg_dict[SQL_QUERY_KEY]
+                        yield ExpandableMarkdown(query, language="sql", truncated_lines=8, classes="rich-output-sql")
+                        del arg_dict[SQL_QUERY_KEY]
+
+                    display_args = arg_dict[:max_args_length] + "…" if len(arg_dict) > max_args_length else arg_dict
+                    yield Static(f"Args: {display_args}", classes="rich-arguments-text")
+
+        # Output - check if it's JSON and prettify if so
+        if self.output:
+            try:
+                json_output = json.loads(self.output)
+            except json.JSONDecodeError:
+                json_output = None
+            if json_output:
+                assert json_output.get("type") == "text", "Expected JSON output type to be 'text'"
+                is_json, processed_output = self._prettify_json_output(json_output.get("text", ""))
+            else:
+                # output should always be a JSON string, but if not, treat it as plain text
+                is_json, processed_output = False, self.output
+            with Horizontal(classes="tool-output"):
+                yield Static("└─", classes="tool-output-prefix")
+                with Vertical(classes="tool-output-content"):
+                    if is_json:
+                        # Use ExpandableMarkdown for JSON with syntax highlighting
+                        yield ExpandableMarkdown(
+                            processed_output, language="json", truncated_lines=8, classes="rich-output-json"
+                        )
+                    else:
+                        # Use ExpandableMarkdown for non-JSON content (renders as markdown without code block)
+                        yield ExpandableMarkdown(
+                            processed_output, language="", truncated_lines=5, classes="rich-output-markdown"
+                        )
+
+
+class WebSearchToolMessage(BaseToolMessage):
+    """A widget to display web search results."""
+
+    search_query: reactive[str] = reactive("")
+
+    def __init__(self, query: str, output: str = "", status: MessageStatus = MessageStatus.EXECUTING, **kwargs) -> None:
+        """
+        Construct a WebSearchToolMessage.
+
+        Args:
+            query: The search query.
+            output: The search results as JSON string (optional, can be set later).
+            status: The status of execution.
+            **kwargs: Additional keyword arguments for Widget.
+        """
+        super().__init__(status=status, **kwargs)
+        self.search_query = query
+        self.output = output
+
+    def compose(self) -> ComposeResult:
+        """Create child widgets for the search message."""
+        # Header line
+        header = f"WebSearch({self.search_query})"
+        yield MessageHeader("⏺", header, status=self.status)
+
+        # Process and display search results
+        if self.output:
+            try:
+                result_data = json.loads(self.output)
+                if result_data.get("success") and result_data.get("results"):
+                    with Horizontal(classes="tool-output"):
+                        yield Static("└─", classes="tool-output-prefix")
+                        with Vertical(classes="tool-output-content"):
+                            # Format results as markdown
+                            markdown_results = []
+                            for i, result in enumerate(result_data["results"], 1):
+                                title = result.get("title", "No title")
+                                href = result.get("href", "")
+                                body = result.get("body", "")
+
+                                # Format each result
+                                result_md = f"**{i}. [{title}]({href})**"
+                                if body:
+                                    # Truncate body if too long
+                                    max_body_length = 200
+                                    if len(body) > max_body_length:
+                                        body = body[:max_body_length] + "..."
+                                    result_md += f"\n   {body}"
+                                if href:
+                                    result_md += f"\n   🔗 {href}"
+
+                                markdown_results.append(result_md)
+
+                            # Join all results with spacing
+                            all_results = "\n\n".join(markdown_results)
+
+                            # Add result count message
+                            count_msg = result_data.get("message", "")
+                            if count_msg:
+                                all_results = f"_{count_msg}_\n\n{all_results}"
+
+                            yield ExpandableMarkdown(
+                                all_results, language="", truncated_lines=10, classes="websearch-results"
+                            )
+                else:
+                    # No results or error
+                    with Horizontal(classes="tool-output"):
+                        yield Static("└─", classes="tool-output-prefix")
+                        with Vertical(classes="tool-output-content"):
+                            message = result_data.get("message", "No results found")
+                            yield Static(message, classes="websearch-no-results")
+            except (json.JSONDecodeError, KeyError, TypeError):
+                # Fallback to raw output if JSON parsing fails
+                yield from self._render_output(self.output, truncated_lines=5)
+
+
+class WebFetchToolMessage(BaseToolMessage):
+    """A widget to display fetched web content."""
+
+    fetch_url: reactive[str] = reactive("")
+
+    def __init__(self, url: str, output: str = "", status: MessageStatus = MessageStatus.EXECUTING, **kwargs) -> None:
+        """
+        Construct a WebFetchToolMessage.
+
+        Args:
+            url: The URL that was fetched.
+            output: The fetched content as Markdown (optional, can be set later).
+            status: The status of execution.
+            **kwargs: Additional keyword arguments for Widget.
+        """
+        super().__init__(status=status, **kwargs)
+        self.fetch_url = url
+        self.output = output
+
+    def compose(self) -> ComposeResult:
+        """Create child widgets for the fetch message."""
+        # Header line
+        header = f"WebFetch({self.fetch_url})"
+        yield MessageHeader("⏺", header, status=self.status)
+
+        # Display fetched content
+        if self.output:
+            with Horizontal(classes="tool-output"):
+                yield Static("└─", classes="tool-output-prefix")
+                with Vertical(classes="tool-output-content"):
+                    # Check if it's an error message
+                    if self.output.startswith("Error:"):
+                        yield Static(self.output, classes="webfetch-error")
+                    else:
+                        # Display as expandable markdown content
+                        # Default to showing first 15 lines since web content can be long
+                        yield ExpandableMarkdown(
+                            self.output, language="", truncated_lines=15, classes="webfetch-content"
+                        )

vibecore/widgets/tool_messages.tcss

@@ -286,4 +286,98 @@ MCPToolMessage {
             width: 1fr;
         }
     }
+}
+
+RichToolMessage {
+    Horizontal.rich-arguments {
+        height: auto;
+
+        &> .rich-arguments-prefix {
+            height: 1;
+            width: 5;
+            padding-left: 2;
+            padding-right: 1;
+            color: $text-muted;
+        }
+
+        &> Vertical.rich-arguments-content {
+            height: auto;
+            width: 1fr;
+
+            .rich-arguments-label {
+                color: $text-muted;
+                # margin-bottom: 1;
+            }
+
+            .rich-arguments-text {
+                color: $text-muted;
+                text-overflow: ellipsis;
+            }
+        }
+    }
+    
+    Horizontal.tool-output {
+        height: auto;
+
+        &> .tool-output-prefix {
+            height: 1;
+            width: 5;
+            padding-left: 2;
+            padding-right: 1;
+            color: $text-muted;
+        }
+
+        &> Vertical.tool-output-content {
+            height: auto;
+            width: 1fr;
+        }
+    }
+}
+
+WebSearchToolMessage {
+    Horizontal.tool-output {
+        height: auto;
+
+        &> .tool-output-prefix {
+            height: 1;
+            width: 5;
+            padding-left: 2;
+            padding-right: 1;
+        }
+
+        &> Vertical.tool-output-content {
+            height: auto;
+
+            &> .tool-output-content {
+                # color: $text-muted;
+            }
+
+            &> .tool-output-content-more {
+            }
+            }
+    }
+}
+
+WebFetchToolMessage {
+    Horizontal.tool-output {
+        height: auto;
+
+        &> .tool-output-prefix {
+            height: 1;
+            width: 5;
+            padding-left: 2;
+            padding-right: 1;
+        }
+
+        &> Vertical.tool-output-content {
+            height: auto;
+
+            &> .tool-output-content {
+                # color: $text-muted;
+            }
+
+            &> .tool-output-content-more {
+            }
+            }
+    }
 }

{vibecore-0.2.0.dist-info → vibecore-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vibecore
-Version: 0.2.0
+Version: 0.3.0
 Summary: Build your own AI-powered automation tools in the terminal with this extensible agent framework
 Project-URL: Homepage, https://github.com/serialx/vibecore
 Project-URL: Repository, https://github.com/serialx/vibecore
@@ -27,6 +27,9 @@ Classifier: Topic :: Terminals
 Classifier: Topic :: Text Processing :: Linguistic
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
+Requires-Dist: ddgs>=9.5.4
+Requires-Dist: html2text>=2024.2.26
+Requires-Dist: httpx>=0.24.0
 Requires-Dist: litellm>=1.72.4
 Requires-Dist: openai-agents[litellm]>=0.2.2
 Requires-Dist: pydantic-settings>=2.10.1
@@ -65,6 +68,7 @@ Built on [Textual](https://textual.textualize.io/) and the [OpenAI Agents SDK](h
 
 ### Key Features
 
+- **Flow Mode (Experimental)** - Build structured agent-based applications with programmatic conversation control
 - **AI-Powered Chat Interface** - Interact with state-of-the-art language models through an intuitive terminal interface
 - **Rich Tool Integration** - Built-in tools for file operations, shell commands, Python execution, and task management
 - **MCP Support** - Connect to external tools and services via Model Context Protocol servers
@@ -79,6 +83,26 @@ Built on [Textual](https://textual.textualize.io/) and the [OpenAI Agents SDK](h
 ### Prerequisites
 
 - Python 3.11 or higher
+- (Optional) [uv](https://docs.astral.sh/uv/) for quick testing and better package management
+
+### Quick Test (No Installation)
+
+Try vibecore instantly without installing it:
+
+```bash
+# Install uv if you don't have it (optional)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Configure your API key
+export ANTHROPIC_API_KEY="your-api-key-here"
+# or
+export OPENAI_API_KEY="your-api-key-here"
+
+# Run vibecore directly with uvx
+uvx vibecore
+```
+
+This will download and run vibecore in an isolated environment without affecting your system Python installation.
 
 ### Install from PyPI
 
@@ -136,6 +160,88 @@ Once vibecore is running, you can:
 - `/help` - Show help and keyboard shortcuts
 - `/clear` - Clear the current session and start a new one
 
+## Flow Mode (Experimental)
+
+Flow Mode is vibecore's **key differentiator** - it transforms the framework from a chat interface into a platform for building structured agent-based applications with programmatic conversation control.
+
+### What is Flow Mode?
+
+Flow Mode allows you to:
+- **Define custom conversation logic** that controls how agents process user input
+- **Build multi-step workflows** with defined sequences and decision points
+- **Orchestrate multiple agents** with handoffs and shared context
+- **Maintain conversation state** across interactions
+- **Create agent-based applications** rather than just chatbots
+
+### Example: Simple Flow
+
+```python
+import asyncio
+from agents import Agent, Runner
+from vibecore.flow import flow, UserInputFunc
+from vibecore.context import VibecoreContext
+
+# Define your agent with tools
+agent = Agent[VibecoreContext](
+    name="Assistant",
+    instructions="You are a helpful assistant",
+    tools=[...],  # Your tools here
+)
+
+# Define your conversation logic
+async def logic(app, ctx: VibecoreContext, user_input: UserInputFunc):
+    # Get user input programmatically
+    user_message = await user_input("What would you like to do?")
+    
+    # Process with agent
+    result = Runner.run_streamed(
+        agent,
+        input=user_message,
+        context=ctx,
+        session=app.session,
+    )
+    
+    # Handle the response
+    app.current_worker = app.handle_streamed_response(result)
+    await app.current_worker.wait()
+
+# Run the flow
+async def main():
+    await flow(agent, logic)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Example: Multi-Agent Customer Service
+
+Flow Mode shines when building complex multi-agent systems. See `examples/customer_service.py` for a complete implementation featuring:
+
+- **Triage Agent**: Routes requests to appropriate specialists
+- **FAQ Agent**: Handles frequently asked questions
+- **Booking Agent**: Manages seat reservations
+- **Agent Handoffs**: Seamless transitions between agents with context preservation
+- **Shared State**: Maintains customer information across the conversation
+
+### Key Components
+
+- **`flow()`**: Entry point that sets up the Vibecore app with your custom logic
+- **`logic()`**: Your async function that controls the conversation flow
+- **`UserInputFunc`**: Provides programmatic user input collection
+- **`VibecoreContext`**: Shared state across tools and agents
+- **Agent Handoffs**: Transfer control between specialized agents
+
+### Use Cases
+
+Flow Mode enables building:
+- **Customer service systems** with routing and escalation
+- **Guided workflows** for complex tasks
+- **Interactive tutorials** with step-by-step guidance
+- **Task automation** with human-in-the-loop controls
+- **Multi-stage data processing** pipelines
+
+The examples in the `examples/` directory are adapted from the official OpenAI Agents SDK with minimal modifications, demonstrating how easily you can build sophisticated agent applications with vibecore.
+
 ### Available Tools
 
 vibecore comes with powerful built-in tools: