agentic-cli 0.3.0__tar.gz → 0.3.2__tar.gz

{agentic_cli-0.3.0 → agentic_cli-0.3.2}/.gitignore

@@ -46,3 +46,7 @@ CLAUDE.md
 plans/
 docs/
 changes/
+.research_demo/
+
+# Git worktrees
+.worktrees/

{agentic_cli-0.3.0 → agentic_cli-0.3.2}/CHANGELOG.md

@@ -5,6 +5,50 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.2] - 2026-02-01
+
+### Added
+
+- **Web Fetch Tool**: Full-featured web content fetching with LLM summarization
+  - HTML-to-Markdown conversion with html2text
+  - Robots.txt compliance checking
+  - SSRF protection and URL validation
+  - Caching and redirect handling
+- **Web Search Tool**: Pluggable web search with backend abstraction
+- **arXiv Integration**: Enhanced arXiv search with rate limiting, caching, advanced query options, and paper analysis tools
+- **LLM Event Logging**: Debug logging for model interactions
+- **Task Progress Events**: `verbose_thinking` setting for detailed task progress display
+
+### Changed
+
+- **CLI Architecture Refactoring**:
+  - Extracted `WorkflowController` and `MessageProcessor` from `BaseCLIApp` for better separation of concerns
+  - Added `background_init` context manager to `WorkflowController`
+  - Added public query methods to managers to reduce command-workflow coupling
+- **BaseWorkflowManager**: Moved shared implementations from ADK/LangGraph managers to base class
+- **Code Quality**: Added enums for string literals, improved `TaskGraph` encapsulation
+- **Settings**: Use app-specific paths and generic settings application
+
+### Fixed
+
+- Circular import in workflow module
+- Web search tool integration issues
+- arXiv cache unbounded growth (added size limit)
+- Webfetch redirect response structure alignment with spec
+
+## [0.3.1] - 2026-01-28
+
+### Added
+
+- **Task Progress Display**: Thinking box now shows dynamic task progress with status icons (◐ ☐ ✓ ✗)
+- `TASK_PROGRESS` event type for signaling task graph updates
+- `TaskGraph.to_compact_display()` for condensed status display
+
+### Changed
+
+- **Background Initialization**: Workflow manager now initializes services in background, eliminating first-message lag
+- Simplified LangGraph imports - removed `_import_langgraph` helper in favor of direct imports
+
 ## [0.3.0] - 2025-01-27
 
 ### Added

{agentic_cli-0.3.0 → agentic_cli-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-cli
-Version: 0.3.0
+Version: 0.3.2
 Summary: A framework for building domain-specific agentic CLI applications
 Project-URL: Homepage, https://github.com/shoom1/agentic-cli
 Project-URL: Repository, https://github.com/shoom1/agentic-cli
@@ -48,7 +48,7 @@ Agentic CLI provides the core infrastructure for building interactive CLI applic
 - **Pluggable Orchestration**: Choose between Google ADK or LangGraph for agent workflows
 - **Rich Terminal UI**: Thinking boxes, markdown rendering, and streaming responses via `thinking-prompt`
 - **Declarative Agents**: Define agents with simple configuration objects
-- **Built-in Tools**: Python execution, knowledge base search, web search
+- **Built-in Tools**: Python execution, knowledge base, web search, web fetch, arXiv search
 - **Session Persistence**: Save and restore conversation sessions
 - **Type-safe Configuration**: Settings management with pydantic-settings
 
@@ -60,6 +60,8 @@ Agentic CLI provides the core infrastructure for building interactive CLI applic
 │  - Terminal UI (thinking-prompt)                                    │
 │  - Command registry (/help, /status, /clear, etc.)                  │
 │  - Message history                                                  │
+│  - Background initialization (no first-message lag)                 │
+│  - Task progress display in thinking box                            │
 └─────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
@@ -249,6 +251,10 @@ class MySettings(BaseSettings):
 | `orchestrator` | `AGENTIC_ORCHESTRATOR` | "adk" | Orchestrator: adk or langgraph |
 | `workspace_dir` | `AGENTIC_WORKSPACE_DIR` | ~/.agentic | Storage directory |
 | `log_level` | `AGENTIC_LOG_LEVEL` | "warning" | Logging level |
+| `tavily_api_key` | `TAVILY_API_KEY` | None | Tavily API key for web search |
+| `brave_api_key` | `BRAVE_API_KEY` | None | Brave Search API key |
+| `search_backend` | `AGENTIC_SEARCH_BACKEND` | Auto | Web search provider (tavily/brave) |
+| `webfetch_model` | `AGENTIC_WEBFETCH_MODEL` | Auto | Model for web content summarization |
 
 ### Settings Context
 
@@ -363,6 +369,59 @@ np.mean(data)
 
 Allowed modules: numpy, pandas, scipy, math, json, datetime, collections, itertools, re, random
 
+#### Web Search
+
+Search the web using pluggable backends (Tavily or Brave):
+
+```python
+from agentic_cli.tools import web_search
+
+# Use as agent tool
+agent = AgentConfig(
+    name="researcher",
+    tools=[web_search],
+)
+
+# Or call directly
+results = web_search("Python async programming", max_results=5)
+# Returns: {"results": [{"title": "...", "url": "...", "snippet": "..."}], ...}
+```
+
+Backends auto-select based on available API keys. Set `TAVILY_API_KEY` or `BRAVE_API_KEY`.
+
+#### Web Fetch
+
+Fetch web content and summarize with LLM:
+
+```python
+from agentic_cli.tools import web_fetch
+
+result = web_fetch(
+    url="https://example.com/article",
+    prompt="Extract the main points from this article",
+)
+# Returns: {"url": "...", "summary": "...", "content_length": ...}
+```
+
+Features: URL validation, robots.txt compliance, SSRF protection, content caching.
+
+#### ArXiv Search
+
+Search and analyze academic papers:
+
+```python
+from agentic_cli.tools import search_arxiv, fetch_arxiv_paper, analyze_arxiv_paper
+
+# Search papers
+results = search_arxiv("transformer attention", max_results=10, categories=["cs.CL"])
+
+# Fetch paper details
+paper = fetch_arxiv_paper("1706.03762")  # "Attention Is All You Need"
+
+# Analyze with LLM
+analysis = await analyze_arxiv_paper("1706.03762", "Summarize the key contributions")
+```
+
 #### KnowledgeBaseManager
 
 Semantic search over documents:
@@ -430,6 +489,7 @@ WorkflowEvent types for UI integration:
 | `CODE_EXECUTION` | Code execution result | outcome |
 | `ERROR` | Error message | recoverable, error_code |
 | `USER_INPUT_REQUIRED` | Tool needs user input | request_id, prompt |
+| `TASK_PROGRESS` | Task graph update | current_task_description, progress |
 
 ### Processing Events
 
@@ -445,12 +505,31 @@ async for event in manager.process(message, user_id="user1"):
         print(f"Result: {event.metadata['result']}")
 ```
 
+### Task Progress Display
+
+When using a task graph for planning, the CLI thinking box dynamically shows task progress:
+
+```
+Calling: search_web
+─── Tasks: 2/5 ───
+◐ Researching topic
+☐ Analyzing results
+☐ Writing summary
+```
+
+Status icons:
+- `◐` In progress
+- `☐` Pending
+- `✓` Completed
+- `✗` Failed
+
 ## Examples
 
 See the `examples/` directory for complete working examples:
 
 - **hello_agent.py** - Simple assistant using Google ADK
 - **hello_langgraph.py** - Same assistant using LangGraph orchestration
+- **webfetch_demo.py** - Web fetching and summarization demo
 - **research_demo/** - Full-featured research assistant with memory, planning, and file operations
 
 Run examples:
@@ -491,7 +570,9 @@ agentic-cli/
 │   ├── config.py             # BaseSettings, SettingsContext
 │   ├── cli/
 │   │   ├── app.py            # BaseCLIApp
-│   │   └── commands.py       # Command, CommandRegistry
+│   │   ├── commands.py       # Command, CommandRegistry
+│   │   ├── workflow_controller.py  # Workflow orchestration
+│   │   └── message_processor.py    # Event stream processing
 │   ├── workflow/
 │   │   ├── events.py         # WorkflowEvent, EventType
 │   │   ├── config.py         # AgentConfig
@@ -502,12 +583,15 @@ agentic-cli/
 │   │       ├── persistence/  # Checkpointers and stores
 │   │       └── tools/        # Shell, file search tools
 │   ├── tools/
-│   │   └── executor.py       # SafePythonExecutor
+│   │   ├── executor.py       # SafePythonExecutor
+│   │   ├── search.py         # Web search (Tavily, Brave)
+│   │   └── webfetch/         # Web content fetching
 │   └── knowledge_base/
 │       └── manager.py        # KnowledgeBaseManager
 ├── examples/
 │   ├── hello_agent.py
 │   ├── hello_langgraph.py
+│   ├── webfetch_demo.py
 │   └── research_demo/        # Full-featured example
 └── tests/
 ```

{agentic_cli-0.3.0 → agentic_cli-0.3.2}/README.md

@@ -9,7 +9,7 @@ Agentic CLI provides the core infrastructure for building interactive CLI applic
 - **Pluggable Orchestration**: Choose between Google ADK or LangGraph for agent workflows
 - **Rich Terminal UI**: Thinking boxes, markdown rendering, and streaming responses via `thinking-prompt`
 - **Declarative Agents**: Define agents with simple configuration objects
-- **Built-in Tools**: Python execution, knowledge base search, web search
+- **Built-in Tools**: Python execution, knowledge base, web search, web fetch, arXiv search
 - **Session Persistence**: Save and restore conversation sessions
 - **Type-safe Configuration**: Settings management with pydantic-settings
 
@@ -21,6 +21,8 @@ Agentic CLI provides the core infrastructure for building interactive CLI applic
 │  - Terminal UI (thinking-prompt)                                    │
 │  - Command registry (/help, /status, /clear, etc.)                  │
 │  - Message history                                                  │
+│  - Background initialization (no first-message lag)                 │
+│  - Task progress display in thinking box                            │
 └─────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
@@ -210,6 +212,10 @@ class MySettings(BaseSettings):
 | `orchestrator` | `AGENTIC_ORCHESTRATOR` | "adk" | Orchestrator: adk or langgraph |
 | `workspace_dir` | `AGENTIC_WORKSPACE_DIR` | ~/.agentic | Storage directory |
 | `log_level` | `AGENTIC_LOG_LEVEL` | "warning" | Logging level |
+| `tavily_api_key` | `TAVILY_API_KEY` | None | Tavily API key for web search |
+| `brave_api_key` | `BRAVE_API_KEY` | None | Brave Search API key |
+| `search_backend` | `AGENTIC_SEARCH_BACKEND` | Auto | Web search provider (tavily/brave) |
+| `webfetch_model` | `AGENTIC_WEBFETCH_MODEL` | Auto | Model for web content summarization |
 
 ### Settings Context
 
@@ -324,6 +330,59 @@ np.mean(data)
 
 Allowed modules: numpy, pandas, scipy, math, json, datetime, collections, itertools, re, random
 
+#### Web Search
+
+Search the web using pluggable backends (Tavily or Brave):
+
+```python
+from agentic_cli.tools import web_search
+
+# Use as agent tool
+agent = AgentConfig(
+    name="researcher",
+    tools=[web_search],
+)
+
+# Or call directly
+results = web_search("Python async programming", max_results=5)
+# Returns: {"results": [{"title": "...", "url": "...", "snippet": "..."}], ...}
+```
+
+Backends auto-select based on available API keys. Set `TAVILY_API_KEY` or `BRAVE_API_KEY`.
+
+#### Web Fetch
+
+Fetch web content and summarize with LLM:
+
+```python
+from agentic_cli.tools import web_fetch
+
+result = web_fetch(
+    url="https://example.com/article",
+    prompt="Extract the main points from this article",
+)
+# Returns: {"url": "...", "summary": "...", "content_length": ...}
+```
+
+Features: URL validation, robots.txt compliance, SSRF protection, content caching.
+
+#### ArXiv Search
+
+Search and analyze academic papers:
+
+```python
+from agentic_cli.tools import search_arxiv, fetch_arxiv_paper, analyze_arxiv_paper
+
+# Search papers
+results = search_arxiv("transformer attention", max_results=10, categories=["cs.CL"])
+
+# Fetch paper details
+paper = fetch_arxiv_paper("1706.03762")  # "Attention Is All You Need"
+
+# Analyze with LLM
+analysis = await analyze_arxiv_paper("1706.03762", "Summarize the key contributions")
+```
+
 #### KnowledgeBaseManager
 
 Semantic search over documents:
@@ -391,6 +450,7 @@ WorkflowEvent types for UI integration:
 | `CODE_EXECUTION` | Code execution result | outcome |
 | `ERROR` | Error message | recoverable, error_code |
 | `USER_INPUT_REQUIRED` | Tool needs user input | request_id, prompt |
+| `TASK_PROGRESS` | Task graph update | current_task_description, progress |
 
 ### Processing Events
 
@@ -406,12 +466,31 @@ async for event in manager.process(message, user_id="user1"):
         print(f"Result: {event.metadata['result']}")
 ```
 
+### Task Progress Display
+
+When using a task graph for planning, the CLI thinking box dynamically shows task progress:
+
+```
+Calling: search_web
+─── Tasks: 2/5 ───
+◐ Researching topic
+☐ Analyzing results
+☐ Writing summary
+```
+
+Status icons:
+- `◐` In progress
+- `☐` Pending
+- `✓` Completed
+- `✗` Failed
+
 ## Examples
 
 See the `examples/` directory for complete working examples:
 
 - **hello_agent.py** - Simple assistant using Google ADK
 - **hello_langgraph.py** - Same assistant using LangGraph orchestration
+- **webfetch_demo.py** - Web fetching and summarization demo
 - **research_demo/** - Full-featured research assistant with memory, planning, and file operations
 
 Run examples:
@@ -452,7 +531,9 @@ agentic-cli/
 │   ├── config.py             # BaseSettings, SettingsContext
 │   ├── cli/
 │   │   ├── app.py            # BaseCLIApp
-│   │   └── commands.py       # Command, CommandRegistry
+│   │   ├── commands.py       # Command, CommandRegistry
+│   │   ├── workflow_controller.py  # Workflow orchestration
+│   │   └── message_processor.py    # Event stream processing
 │   ├── workflow/
 │   │   ├── events.py         # WorkflowEvent, EventType
 │   │   ├── config.py         # AgentConfig
@@ -463,12 +544,15 @@ agentic-cli/
 │   │       ├── persistence/  # Checkpointers and stores
 │   │       └── tools/        # Shell, file search tools
 │   ├── tools/
-│   │   └── executor.py       # SafePythonExecutor
+│   │   ├── executor.py       # SafePythonExecutor
+│   │   ├── search.py         # Web search (Tavily, Brave)
+│   │   └── webfetch/         # Web content fetching
 │   └── knowledge_base/
 │       └── manager.py        # KnowledgeBaseManager
 ├── examples/
 │   ├── hello_agent.py
 │   ├── hello_langgraph.py
+│   ├── webfetch_demo.py
 │   └── research_demo/        # Full-featured example
 └── tests/
 ```

{agentic_cli-0.3.0 → agentic_cli-0.3.2}/environment.yml

@@ -5,6 +5,7 @@ channels:
 dependencies:
   - python=3.12
   - pip
+  - html2text
   - pip:
     - -e .
     - -e .[dev]

{agentic_cli-0.3.0 → agentic_cli-0.3.2}/examples/research_demo/agents.py

@@ -5,7 +5,7 @@ Only app-specific tools (file operations, shell) are defined locally.
 """
 
 from agentic_cli.workflow import AgentConfig
-from agentic_cli.tools import memory_tools, planning_tools, hitl_tools
+from agentic_cli.tools import memory_tools, planning_tools, hitl_tools, web_search, search_arxiv, fetch_arxiv_paper, analyze_arxiv_paper
 
 # App-specific tools (file operations and shell)
 from examples.research_demo.tools import (
@@ -47,6 +47,17 @@ RESEARCH_AGENT_PROMPT = """You are a research assistant with memory and planning
 **Shell Commands**
 - `run_safe_command(command)` - Run safe shell commands (ls, cat, grep, etc.)
 
+**Web Search**
+- `web_search(query, max_results)` - Search the web for current information
+
+**Academic Search**
+- `search_arxiv(query, max_results, categories, sort_by, sort_order, date_from, date_to)` - Search arXiv for academic papers
+  - sort_by: "relevance", "lastUpdatedDate", or "submittedDate"
+  - sort_order: "ascending" or "descending"
+  - date_from/date_to: filter by date (YYYY-MM-DD format)
+- `fetch_arxiv_paper(arxiv_id)` - Get detailed info about a specific paper by ID
+- `analyze_arxiv_paper(arxiv_id, prompt)` - Analyze a paper with LLM (async)
+
 **Checkpoints**
 - `create_checkpoint(name, content, content_type)` - Create a review point
 
@@ -159,6 +170,12 @@ AGENT_CONFIGS = [
             compare_versions,
             # App-specific shell tool
             run_safe_command,
+            # Web search
+            web_search,
+            # Academic search
+            search_arxiv,
+            fetch_arxiv_paper,
+            analyze_arxiv_paper,
         ],
         description="Research assistant with memory and planning capabilities",
     ),

agentic_cli-0.3.2/examples/research_demo/app.py

@@ -0,0 +1,81 @@
+"""Main application for the Research Demo.
+
+Showcases framework features through a research assistant agent
+with memory, planning, file operations, shell commands, and HITL.
+
+Feature managers (MemoryManager, TaskGraph, CheckpointManager) are
+auto-created by the workflow manager based on tool requirements.
+"""
+
+from rich.panel import Panel
+from rich.text import Text
+
+from agentic_cli import BaseCLIApp
+from agentic_cli.cli import AppInfo
+from agentic_cli.logging import Loggers
+
+from examples.research_demo.agents import AGENT_CONFIGS
+from examples.research_demo.commands import DEMO_COMMANDS
+from examples.research_demo.settings import ResearchDemoSettings, get_settings
+
+logger = Loggers.cli()
+
+
+def _create_app_info() -> AppInfo:
+    """Create the application info for the welcome message."""
+    text = Text()
+    text.append("Research Demo\n\n", style="bold cyan")
+    text.append("A research assistant with memory and planning capabilities.\n\n", style="dim")
+    text.append("Features:\n", style="bold")
+    text.append("  - Working memory (session context)\n", style="dim")
+    text.append("  - Long-term memory (persistent learnings)\n", style="dim")
+    text.append("  - Task planning (research plans)\n", style="dim")
+    text.append("  - File operations (save/compare findings)\n", style="dim")
+    text.append("  - Shell commands (safe execution)\n", style="dim")
+    text.append("\n")
+    text.append("Commands:\n", style="bold")
+    text.append("  /memory  - Show memory state\n", style="cyan")
+    text.append("  /plan    - Show task plan\n", style="cyan")
+    text.append("  /files   - List saved findings\n", style="cyan")
+    text.append("  /help    - All commands\n", style="cyan")
+
+    return AppInfo(
+        name="Research Demo",
+        version="0.1.0",
+        welcome_message=lambda: Panel(text, border_style="cyan"),
+        echo_thinking=False,
+    )
+
+
+class ResearchDemoApp(BaseCLIApp):
+    """Research Demo CLI Application.
+
+    Demonstrates framework features:
+    - Memory: Working memory (session) + Long-term memory (persistent)
+    - Planning: Task graphs with dependencies
+    - File Operations: Save/read/compare findings
+    - Shell Commands: Safe command execution
+    - HITL: Checkpoints for review
+
+    Feature managers are auto-created by the workflow manager based on
+    the @requires decorators on framework tools.
+    """
+
+    def __init__(self, settings: ResearchDemoSettings | None = None) -> None:
+        super().__init__(
+            app_info=_create_app_info(),
+            agent_configs=AGENT_CONFIGS,
+            settings=settings or get_settings(),
+        )
+
+    def register_commands(self) -> None:
+        """Register demo-specific commands."""
+        for command_class in DEMO_COMMANDS:
+            self.command_registry.register(command_class())
+
+    def get_ui_setting_keys(self) -> list[str]:
+        """Get field names to display in the settings dialog.
+
+        Includes verbose_thinking in addition to standard settings.
+        """
+        return ["model", "thinking_effort", "log_activity", "verbose_thinking"]

{agentic_cli-0.3.0 → agentic_cli-0.3.2}/examples/research_demo/commands.py

@@ -46,15 +46,12 @@ class MemoryCommand(Command):
         working_table.add_column("Tags", style="dim")
 
         if memory_manager:
-            working_mem = memory_manager.working
-            for key in working_mem.list():
-                entry = working_mem._entries.get(key)
-                if entry:
-                    value_str = str(entry.value)
-                    if len(value_str) > 50:
-                        value_str = value_str[:50] + "..."
-                    tags_str = ", ".join(entry.tags) if entry.tags else ""
-                    working_table.add_row(key, value_str, tags_str)
+            for key, (value, tags) in memory_manager.get_working_entries().items():
+                value_str = str(value)
+                if len(value_str) > 50:
+                    value_str = value_str[:50] + "..."
+                tags_str = ", ".join(tags) if tags else ""
+                working_table.add_row(key, value_str, tags_str)
 
         if working_table.row_count == 0:
             working_table.add_row("(empty)", "", "")
@@ -173,7 +170,7 @@ class ApprovalsCommand(Command):
             app.session.add_message("system", "Approval manager not initialized")
             return
 
-        pending = approval_manager._pending
+        pending = approval_manager.get_pending_requests()
 
         if not pending:
             app.session.add_message("system", "No pending approval requests")
@@ -186,7 +183,7 @@ class ApprovalsCommand(Command):
         table.add_column("Description", style="white")
         table.add_column("Risk", style="red")
 
-        for request_id, request in pending.items():
+        for request in pending:
             table.add_row(
                 request.id,
                 request.tool,
@@ -218,21 +215,13 @@ class CheckpointsCommand(Command):
             app.session.add_message("system", "Checkpoint manager not initialized")
             return
 
-        checkpoints = checkpoint_manager._checkpoints
-        resolved = checkpoint_manager._results
-
-        # Filter to unresolved checkpoints
-        unresolved = {
-            cp_id: cp
-            for cp_id, cp in checkpoints.items()
-            if cp_id not in resolved
-        }
+        unresolved = checkpoint_manager.get_unresolved()
 
         if not unresolved:
             app.session.add_message("system", "No checkpoints awaiting review")
             return
 
-        for cp_id, checkpoint in unresolved.items():
+        for checkpoint in unresolved:
             content_preview = str(checkpoint.content)
             if len(content_preview) > 200:
                 content_preview = content_preview[:200] + "..."
@@ -339,7 +328,7 @@ class ClearPlanCommand(Command):
         task_graph = app.workflow.task_graph if app.workflow else None
 
         if task_graph:
-            task_graph._tasks.clear()
+            task_graph.clear()
             app.session.add_success("Task plan cleared")
         else:
             app.session.add_error("Task graph not initialized")

{agentic_cli-0.3.0 → agentic_cli-0.3.2}/examples/research_demo/settings.py

@@ -31,12 +31,12 @@ class ResearchDemoSettings(BaseSettings):
     app_name: str = Field(default="research_demo")
     workspace_dir: Path = Field(default=Path.home() / ".research_demo")
 
-    # Demo-specific setting with UI metadata
-    verbose_output: bool = Field(
+    # Override verbose_thinking default for concise mode
+    verbose_thinking: bool = Field(
         default=False,
-        title="Verbose Output",
+        title="Verbose Thinking",
         description="Show detailed thinking output (default: concise mode)",
-        json_schema_extra={"ui_order": 40},
+        json_schema_extra={"ui_order": 35},
     )