vibecore 0.2.0__tar.gz → 0.3.0b1__tar.gz

{vibecore-0.2.0 → vibecore-0.3.0b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vibecore
-Version: 0.2.0
+Version: 0.3.0b1
 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,8 @@ 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: litellm>=1.72.4
 Requires-Dist: openai-agents[litellm]>=0.2.2
 Requires-Dist: pydantic-settings>=2.10.1
@@ -65,6 +67,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 +82,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 +159,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:

{vibecore-0.2.0 → vibecore-0.3.0b1}/README.md

@@ -29,6 +29,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
@@ -43,6 +44,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
 
@@ -100,6 +121,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:

{vibecore-0.2.0 → vibecore-0.3.0b1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vibecore"
-version = "0.2.0"
+version = "0.3.0b1"
 description = "Build your own AI-powered automation tools in the terminal with this extensible agent framework"
 readme = "README.md"
 authors = [
@@ -44,6 +44,8 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
+    "ddgs>=9.5.4",
+    "html2text>=2024.2.26",
     "litellm>=1.72.4",
     "openai-agents[litellm]>=0.2.2",
     "pydantic-settings>=2.10.1",

{vibecore-0.2.0 → vibecore-0.3.0b1}/src/vibecore/agents/default.py

@@ -1,8 +1,7 @@
 from typing import TYPE_CHECKING
 
-from agents import Agent, ModelSettings
+from agents import Agent
 from agents.extensions.handoff_prompt import prompt_with_handoff_instructions
-from openai.types import Reasoning
 
 from vibecore.context import VibecoreContext
 from vibecore.settings import settings
@@ -11,6 +10,8 @@ from vibecore.tools.python.tools import execute_python
 from vibecore.tools.shell.tools import bash, glob, grep, ls
 from vibecore.tools.task.tools import task
 from vibecore.tools.todo.tools import todo_read, todo_write
+from vibecore.tools.webfetch.tools import webfetch
+from vibecore.tools.websearch.tools import websearch
 
 from .prompts import COMMON_PROMPT
 
@@ -50,26 +51,20 @@ def create_default_agent(mcp_servers: list["MCPServer"] | None = None) -> Agent[
         grep,
         ls,
         task,
+        websearch,
+        webfetch,
     ]
     instructions = INSTRUCTIONS
 
     instructions = prompt_with_handoff_instructions(instructions)
 
-    # Configure reasoning based on settings
-    reasoning_config = Reasoning(summary="auto")
-    if settings.reasoning_effort is not None:
-        reasoning_config = Reasoning(effort=settings.reasoning_effort, summary="auto")
-
     return Agent[VibecoreContext](
         name="Vibecore Agent",
         handoff_description="A versatile general-purpose assistant",
         instructions=instructions,
         tools=tools,
         model=settings.model,
-        model_settings=ModelSettings(
-            include_usage=True,  # Ensure token usage is tracked in streaming mode
-            reasoning=reasoning_config,
-        ),
+        model_settings=settings.default_model_settings,
         handoffs=[],
         mcp_servers=mcp_servers or [],
     )

vibecore-0.2.0/src/vibecore/agents/task_agent.py → vibecore-0.3.0b1/src/vibecore/agents/task.py

@@ -1,8 +1,7 @@
 """Task-specific agent configuration for executing delegated tasks."""
 
-from agents import Agent, ModelSettings
+from agents import Agent
 from agents.extensions.handoff_prompt import prompt_with_handoff_instructions
-from openai.types import Reasoning
 
 from vibecore.context import VibecoreContext
 from vibecore.settings import settings
@@ -58,9 +57,6 @@ def create_task_agent(prompt: str) -> Agent[VibecoreContext]:
         instructions=instructions,
         tools=tools,
         model=settings.model,
-        model_settings=ModelSettings(
-            include_usage=True,  # Ensure token usage is tracked in streaming mode
-            reasoning=Reasoning(summary="auto"),
-        ),
+        model_settings=settings.default_model_settings,
         handoffs=[],
     )

vibecore-0.3.0b1/src/vibecore/flow.py

@@ -0,0 +1,105 @@
+import asyncio
+import threading
+from collections.abc import Callable, Coroutine
+from typing import Protocol
+
+from agents import Agent
+from textual.pilot import Pilot
+
+from vibecore.context import VibecoreContext
+from vibecore.main import AppIsExiting, VibecoreApp
+from vibecore.widgets.core import MyTextArea
+from vibecore.widgets.messages import SystemMessage
+
+
+class UserInputFunc(Protocol):
+    """Protocol for user input function with optional prompt parameter."""
+
+    async def __call__(self, prompt: str = "") -> str:
+        """Get user input with optional prompt message.
+
+        Args:
+            prompt: Optional prompt to display before getting input.
+
+        Returns:
+            The user's input string.
+        """
+        ...
+
+
+async def flow(
+    agent: Agent,
+    logic: Callable[[VibecoreApp, VibecoreContext, UserInputFunc], Coroutine],
+    headless: bool = False,
+    shutdown: bool = False,
+    disable_user_input: bool = True,
+):
+    ctx = VibecoreContext()
+    app = VibecoreApp(ctx, agent, show_welcome=False)
+
+    app_ready_event = asyncio.Event()
+
+    def on_app_ready() -> None:
+        """Called when app is ready to process events."""
+        app_ready_event.set()
+
+    async def run_app(app: VibecoreApp) -> None:
+        """Run the apps message loop.
+
+        Args:
+            app: App to run.
+        """
+
+        with app._context():
+            try:
+                app._loop = asyncio.get_running_loop()
+                app._thread_id = threading.get_ident()
+                await app._process_messages(
+                    ready_callback=on_app_ready,
+                    headless=headless,
+                )
+            finally:
+                app_ready_event.set()
+
+    async def user_input(prompt: str = "") -> str:
+        if prompt:
+            await app.add_message(SystemMessage(prompt))
+        app.query_one(MyTextArea).disabled = False
+        app.query_one(MyTextArea).focus()
+        user_input = await app.wait_for_user_input()
+        if disable_user_input:
+            app.query_one(MyTextArea).disabled = True
+        return user_input
+
+    async def run_logic(app: VibecoreApp, ctx: VibecoreContext, user_input: UserInputFunc) -> None:
+        try:
+            await logic(app, ctx, user_input)
+        except AppIsExiting:
+            return
+
+    app_task = asyncio.create_task(run_app(app), name=f"with_app({app})")
+    await app_ready_event.wait()
+    pilot = Pilot(app)
+    logic_task: asyncio.Task | None = None
+
+    await pilot._wait_for_screen()
+    if disable_user_input:
+        app.query_one(MyTextArea).disabled = True
+    logic_task = asyncio.create_task(run_logic(app, ctx, user_input), name="logic_task")
+    done, pending = await asyncio.wait([logic_task, app_task], return_when=asyncio.FIRST_COMPLETED)
+
+    # If app has exited and logic is still running, cancel logic
+    if app_task in done and logic_task in pending:
+        logic_task.cancel()
+    # If logic is finished and app is still running
+    elif logic_task in done and app_task in pending:
+        if shutdown:
+            if not headless:
+                await pilot._wait_for_screen()
+                await asyncio.sleep(1.0)
+            app.exit()
+        else:
+            # Enable text input so users can interact freely
+            app.query_one(MyTextArea).disabled = False
+            # Wait until app is exited
+            await app_task

{vibecore-0.2.0 → vibecore-0.3.0b1}/src/vibecore/main.py

@@ -30,7 +30,11 @@ from vibecore.widgets.core import AppFooter, MainScroll, MyTextArea
 from vibecore.widgets.info import Welcome
 from vibecore.widgets.messages import AgentMessage, BaseMessage, MessageStatus, SystemMessage, UserMessage
 
-AgentStatus = Literal["idle", "running"]
+AgentStatus = Literal["idle", "running", "waiting_user_input"]
+
+
+class AppIsExiting(Exception):
+    pass
 
 
 def detect_reasoning_effort(prompt: str) -> Literal["low", "medium", "high"] | None:
@@ -82,6 +86,7 @@ class VibecoreApp(App):
         agent: Agent,
         session_id: str | None = None,
         print_mode: bool = False,
+        show_welcome: bool = True,
     ) -> None:
         """Initialize the Vibecore app with context and agent.
 
@@ -90,6 +95,7 @@ class VibecoreApp(App):
             agent: The Agent instance to use
             session_id: Optional session ID to load existing session
             print_mode: Whether to run in print mode (useful for pipes)
+            show_welcome: Whether to show the welcome message (default: True)
         """
         self.context = context
         self.context.app = self  # Set the app reference in context
@@ -99,6 +105,7 @@ class VibecoreApp(App):
         self.current_worker: Worker[None] | None = None
         self._session_id_provided = session_id is not None  # Track if continuing session
         self.print_mode = print_mode
+        self.show_welcome = show_welcome
         self.message_queue: deque[str] = deque()  # Queue for user messages
 
         # Initialize session based on settings
@@ -124,7 +131,8 @@ class VibecoreApp(App):
         yield Header()
         yield AppFooter()
         with MainScroll(id="messages"):
-            yield Welcome()
+            if self.show_welcome:
+                yield Welcome()
 
     async def on_mount(self) -> None:
         """Called when the app is mounted."""
@@ -162,6 +170,8 @@ class VibecoreApp(App):
         Args:
             message: The message to add
         """
+        if not self.is_running:
+            raise AppIsExiting("App is not running")
         main_scroll = self.query_one("#messages", MainScroll)
         await main_scroll.mount(message)
 
@@ -225,6 +235,14 @@ class VibecoreApp(App):
         else:
             footer.hide_loading()
 
+    async def wait_for_user_input(self) -> str:
+        """Used in flow mode. See examples/basic_agent.py"""
+        self.agent_status = "waiting_user_input"
+        self.user_input_event = asyncio.Event()
+        await self.user_input_event.wait()
+        user_input = self.message_queue.pop()
+        return user_input
+
     async def on_my_text_area_user_message(self, event: MyTextArea.UserMessage) -> None:
         """Handle user messages from the text area."""
         if event.text:
@@ -248,8 +266,11 @@ class VibecoreApp(App):
             await self.add_message(user_message)
             user_message.scroll_visible()
 
-            # If agent is running, queue the message
+            if self.agent_status == "waiting_user_input":
+                self.message_queue.append(event.text)
+                self.user_input_event.set()
             if self.agent_status == "running":
+                # If agent is running, queue the message
                 self.message_queue.append(event.text)
                 log(f"Message queued: {event.text}")
                 footer = self.query_one(AppFooter)
@@ -268,7 +289,7 @@ class VibecoreApp(App):
                 if reasoning_effort is not None:
                     # Create a copy of the agent with updated model settings
                     current_settings = self.agent.model_settings or ModelSettings()
-                    new_reasoning = Reasoning(effort=reasoning_effort, summary="auto")
+                    new_reasoning = Reasoning(effort=reasoning_effort, summary=settings.reasoning_summary)
                     updated_settings = ModelSettings(
                         include_usage=current_settings.include_usage,
                         reasoning=new_reasoning,
@@ -496,8 +517,9 @@ class VibecoreApp(App):
         for welcome in main_scroll.query("Welcome"):
             welcome.remove()
 
-        # Add welcome widget back
-        await main_scroll.mount(Welcome())
+        # Add welcome widget back if show_welcome is True
+        if self.show_welcome:
+            await main_scroll.mount(Welcome())
 
         # Show system message to confirm the clear operation
         system_message = SystemMessage(f"✨ Session cleared! Started new session: {new_session_id}")

{vibecore-0.2.0 → vibecore-0.3.0b1}/src/vibecore/settings.py

@@ -4,9 +4,10 @@ import os
 from pathlib import Path
 from typing import Literal
 
-from agents import Model, OpenAIChatCompletionsModel
+from agents import Model, ModelSettings, OpenAIChatCompletionsModel
 from agents.models.multi_provider import MultiProvider
-from pydantic import BaseModel, Field
+from openai.types import Reasoning
+from pydantic import BaseModel, Field, field_validator
 from pydantic_settings import BaseSettings, PydanticBaseSettingsSource, SettingsConfigDict, YamlConfigSettingsSource
 
 from vibecore.models import AnthropicModel
@@ -92,9 +93,10 @@ class Settings(BaseSettings):
     default_model: str = Field(
         # default="o3",
         # default="gpt-4.1",
+        default="gpt-5",
         # default="qwen3-30b-a3b-mlx@8bit",
         # default="mistralai/devstral-small-2507",
-        default="anthropic/claude-sonnet-4-20250514",
+        # default="anthropic/claude-sonnet-4-20250514",
         # default="anthropic/claude-3-5-haiku-20241022",
         # default="litellm/deepseek/deepseek-chat",
         description="Default model to use for agents (e.g., 'gpt-4.1', 'o3-mini', 'anthropic/claude-sonnet-4')",
@@ -109,6 +111,18 @@ class Settings(BaseSettings):
         default=None,
         description="Default reasoning effort level for agents (null, 'minimal', 'low', 'medium', 'high')",
     )
+    reasoning_summary: Literal["auto", "concise", "detailed"] | None = Field(
+        default="auto",
+        description="Reasoning summary mode ('auto', 'concise', 'detailed', or 'off')",
+    )
+
+    @field_validator("reasoning_summary", mode="before")
+    @classmethod
+    def validate_reasoning_summary(cls, v):
+        """Convert string 'null' to None for reasoning_summary field."""
+        if v == "off" or v == "":
+            return None
+        return v
 
     # Session configuration
     session: SessionSettings = Field(
@@ -138,6 +152,17 @@ class Settings(BaseSettings):
             return OpenAIChatCompletionsModel(self.default_model, openai_provider._get_client())
         return self.default_model
 
+    @property
+    def default_model_settings(self) -> ModelSettings:
+        """Get the default model settings."""
+        return ModelSettings(
+            include_usage=True,
+            reasoning=Reasoning(
+                summary=self.reasoning_summary,
+                effort=self.reasoning_effort,
+            ),
+        )
+
     @classmethod
     def settings_customise_sources(
         cls,

{vibecore-0.2.0 → vibecore-0.3.0b1}/src/vibecore/tools/task/executor.py

@@ -7,7 +7,7 @@ from agents import (
 )
 from textual import log
 
-from vibecore.agents.task_agent import create_task_agent
+from vibecore.agents.task import create_task_agent
 from vibecore.context import VibecoreContext
 from vibecore.settings import settings
 

vibecore-0.3.0b1/src/vibecore/tools/webfetch/__init__.py

@@ -0,0 +1,7 @@
+"""Webfetch tool for fetching and converting web content to Markdown."""
+
+from .executor import fetch_url
+from .models import WebFetchParams
+from .tools import webfetch
+
+__all__ = ["WebFetchParams", "fetch_url", "webfetch"]