agent-framework-lib 0.7.1__tar.gz → 0.8.1__tar.gz

{agent_framework_lib-0.7.1 → agent_framework_lib-0.8.1}/ARCHITECTURE.md

@@ -47,9 +47,17 @@ agent_framework/
 │   ├── multimodal_integration.py  # Multimodal processing
 │   └── ai_content_management.py   # AI content management
 │
-├── tools/                         # Reusable tools
+├── tools/                         # Agent tools & utilities
 │   ├── __init__.py
-│   └── multimodal_tools.py        # Multimodal processing tools
+│   ├── base.py                    # AgentTool base class
+│   ├── shell_tool.py              # ShellTool — CLI command execution
+│   ├── web_fetch_tool.py          # WebFetchTool — web content fetching
+│   ├── multimodal_tools.py        # Multimodal processing tools
+│   ├── activity_callback.py       # Activity callback support
+│   ├── sizing_config.py           # Image sizing configuration
+│   ├── pdf_image_scaler.py        # PDF image scaling
+│   ├── adaptive_pdf_css.py        # Adaptive PDF CSS generation
+│   └── html_content_analyzer.py   # HTML content analysis
 │
 ├── monitoring/                    # Performance & monitoring
 │   ├── __init__.py
@@ -86,7 +94,7 @@ agent_framework/
 | **session/** | Session lifecycle and persistence (memory, MongoDB) |
 | **storage/** | File storage backends and management (Local, S3, MinIO) |
 | **processing/** | Content processing: markdown conversion, multimodal integration, AI content |
-| **tools/** | Reusable tools for various processing tasks |
+| **tools/** | Agent tools: ShellTool (CLI execution), WebFetchTool (web fetching), multimodal processing, and PDF/image sizing utilities |
 | **monitoring/** | Performance monitoring, progress tracking, error handling, logging |
 | **web/** | FastAPI server, HTTP endpoints, web UI |
 | **implementations/** | Framework-specific agent implementations (LlamaIndex, Microsoft) |

{agent_framework_lib-0.7.1/agent_framework_lib.egg-info → agent_framework_lib-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-framework-lib
-Version: 0.7.1
+Version: 0.8.1
 Summary: A comprehensive Python framework for building and serving conversational AI agents with FastAPI
 Author-email: Sebastian Pavel <sebastian@cinco.ai>, Elliott Girard <elliott.girard@icloud.com>
 Maintainer-email: Sebastian Pavel <sebastian@cinco.ai>
@@ -69,6 +69,9 @@ Requires-Dist: nodeenv>=1.8.0
 Requires-Dist: asyncpg>=0.31.0
 Requires-Dist: drawpyo>=0.2.5
 Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: python-pptx>=1.0.0
+Requires-Dist: python-docx>=1.1.0
+Requires-Dist: jsonschema>=4.20.0
 Provides-Extra: llamaindex
 Requires-Dist: llama-index>=0.14.16; extra == "llamaindex"
 Requires-Dist: llama-index-core>=0.14.16; extra == "llamaindex"
@@ -151,8 +154,7 @@ A comprehensive Python framework for building and serving conversational AI agen
 **Key Features:**
 - 🚀 **Quick Setup** - Create agents in 10-15 minutes
 - 🔌 **Easy MCP Integration** - Connect to external tools effortlessly
-- 🛠️ **Off-the-Shelf Tools** - Pre-built tools for files, PDFs, charts, web search (DuckDuckGo), and more
-- 🎯 **Skills System** - On-demand capability loading for token optimization
+- 🎯 **Skills System** - Markdown-based, on-demand capability loading for token optimization
 - 🔄 **Multi-Provider Support** - OpenAI, Anthropic, Gemini
 - 🎯 **Smart Model Routing** - Auto mode selects the best model per query complexity
 - 💾 **Session Management** - Automatic conversation persistence
@@ -531,94 +533,6 @@ Users can override settings per session via the API or web UI:
 - Max tokens
 - System prompt override
 
-## 🛠️ Off-the-Shelf Tools
-
-The framework provides ready-to-use tools for common tasks. Import from `agent_framework.tools`:
-
-### File Management Tools
-
-```python
-from agent_framework.tools import (
-    CreateFileTool,      # Create text files
-    ListFilesTool,       # List stored files
-    ReadFileTool,        # Read file contents
-    GetFilePathTool      # Get file system path
-)
-```
-
-### PDF Generation Tools
-
-```python
-from agent_framework.tools import (
-    CreatePDFFromMarkdownTool,  # Generate PDF from markdown
-    CreatePDFFromHTMLTool,      # Generate PDF from HTML
-    CreatePDFWithImagesTool     # Generate PDF with embedded images
-)
-```
-
-### Chart & Visualization Tools
-
-```python
-from agent_framework.tools import (
-    ChartToImageTool,    # Convert Chart.js config to PNG
-    MermaidToImageTool,  # Convert Mermaid diagram to PNG
-    TableToImageTool     # Convert table data to PNG
-)
-```
-
-### Using Off-the-Shelf Tools
-
-```python
-from agent_framework import LlamaIndexAgent
-from agent_framework.storage.file_system_management import FileStorageFactory
-from agent_framework.tools import CreateFileTool, ListFilesTool, CreatePDFFromMarkdownTool
-
-class MyAgent(LlamaIndexAgent):
-    def __init__(self):
-        super().__init__(
-            agent_id="my_agent",
-            name="File Agent",
-            description="An assistant with file storage and PDF generation capabilities."
-        )
-        self.file_storage = None
-        
-        # Initialize tools
-        self.tools = [
-            CreateFileTool(),
-            ListFilesTool(),
-            CreatePDFFromMarkdownTool()
-        ]
-    
-    async def _ensure_file_storage(self):
-        if self.file_storage is None:
-            self.file_storage = await FileStorageFactory.create_storage_manager()
-    
-    async def configure_session(self, session_configuration):
-        user_id = session_configuration.get('user_id', 'default_user')
-        session_id = session_configuration.get('session_id')
-        
-        await self._ensure_file_storage()
-        
-        # Inject dependencies into tools
-        for tool in self.tools:
-            tool.set_context(
-                file_storage=self.file_storage,
-                user_id=user_id,
-                session_id=session_id
-            )
-        
-        await super().configure_session(session_configuration)
-    
-    def get_agent_tools(self):
-        return [tool.get_tool_function() for tool in self.tools]
-```
-
-**Key Pattern:**
-1. Instantiate tools in `__init__()`
-2. Initialize file storage in `configure_session()`
-3. Inject context with `tool.set_context()`
-4. Return tool functions in `get_agent_tools()`
-
 ## 🔧 Create Custom Tools
 
 Custom tools extend your agent's capabilities. The tool name and docstring are crucial - they tell the agent when and how to use the tool.
@@ -654,43 +568,12 @@ class MyAgent(LlamaIndexAgent):
 
 ### Custom Tool with Dependencies
 
-For tools that need file storage or other dependencies:
+For tools that need file storage or other dependencies, use closures to capture context:
 
 ```python
-from agent_framework.tools.base_tool import AgentTool
-
-class MyCustomTool(AgentTool):
-    """Base class handles dependency injection."""
-    
-    def execute(self, param1: str, param2: int) -> str:
-        """Process data and store results.
-        
-        Args:
-            param1: Description of first parameter
-            param2: Description of second parameter
-            
-        Returns:
-            Result description
-        """
-        # Access injected dependencies
-        user_id = self.user_id
-        session_id = self.session_id
-        file_storage = self.file_storage
-        
-        # Your logic here
-        result = f"Processed {param1} with {param2}"
-        
-        # Store file if needed
-        file_id = await file_storage.store_file(
-            user_id=user_id,
-            session_id=session_id,
-            filename="result.txt",
-            content=result.encode()
-        )
-        
-        return f"Result stored with ID: {file_id}"
+from agent_framework import LlamaIndexAgent
+from agent_framework.storage.file_system_management import FileStorageFactory
 
-# Use in your agent
 class MyAgent(LlamaIndexAgent):
     def __init__(self):
         super().__init__(
@@ -698,19 +581,43 @@ class MyAgent(LlamaIndexAgent):
             name="My Agent",
             description="A helpful assistant with custom tools."
         )
-        self.custom_tool = MyCustomTool()
+        self.file_storage = None
+    
+    async def _ensure_file_storage(self):
+        if self.file_storage is None:
+            self.file_storage = await FileStorageFactory.create_storage_manager()
     
     async def configure_session(self, session_configuration):
-        # Inject dependencies
-        self.custom_tool.set_context(
-            file_storage=self.file_storage,
-            user_id=session_configuration.get('user_id'),
-            session_id=session_configuration.get('session_id')
-        )
+        await self._ensure_file_storage()
+        self._user_id = session_configuration.get('user_id', 'default_user')
+        self._session_id = session_configuration.get('session_id')
         await super().configure_session(session_configuration)
     
     def get_agent_tools(self):
-        return [self.custom_tool.get_tool_function()]
+        storage = self.file_storage
+        user_id = self._user_id
+        session_id = self._session_id
+        
+        async def store_result(param1: str, param2: int) -> str:
+            """Process data and store results.
+            
+            Args:
+                param1: Description of first parameter
+                param2: Description of second parameter
+                
+            Returns:
+                Result description
+            """
+            result = f"Processed {param1} with {param2}"
+            file_id = await storage.store_file(
+                user_id=user_id,
+                session_id=session_id,
+                filename="result.txt",
+                content=result.encode()
+            )
+            return f"Result stored with ID: {file_id}"
+        
+        return [store_result]
 ```
 
 ### Tool Naming Best Practices
@@ -947,6 +854,8 @@ uv add agent-framework-lib[graphiti]
 
 The Skills System provides modular, on-demand capability loading that reduces token consumption by ~80%. Instead of loading all instructions into every system prompt, skills deliver detailed instructions only when needed.
 
+Skills are exclusively defined as `SKILL.md` markdown files with YAML frontmatter, loaded by `MarkdownSkillLoader`. Each skill uses `ShellTool` to execute standalone CLI scripts and `WebFetchTool` for web content retrieval.
+
 ### How It Works
 
 ```
@@ -969,7 +878,7 @@ class MySkillsAgent(LlamaIndexAgent):
             name="Skills Agent",
             description="An agent with on-demand capabilities."
         )
-        # Built-in skills are automatically registered by BaseAgent.__init__
+        # Built-in markdown skills are automatically registered by BaseAgent.__init__
     
     def get_agent_prompt(self) -> str:
         # Skills discovery prompt is automatically appended by BaseAgent
@@ -980,26 +889,40 @@ class MySkillsAgent(LlamaIndexAgent):
         return []  # Only return custom tools specific to your agent
 ```
 
-### Built-in Skills
+### Built-in Skills (21 total)
 
 | Category | Skills |
 |----------|--------|
 | **Visualization** | chart, mermaid, table |
-| **Document** | file, unified_pdf, file_access, excel, drawio |
+| **Document** | file, unified_pdf, file_access, excel, drawio, **powerpoint**, **word** |
 | **Web** | web_search |
-| **Multimodal** | multimodal |
-| **UI** | form, optionsblock, image_display |
+| **Multimodal** | multimodal, **image_gen** |
+| **UI** | form, optionsblock, image_display, **email_template**, **skill_creator** |
+| **Data** | **csv**, **data_format** |
+| **Code** | **code_format** |
+
+**New in v0.9.0:** 8 additional skills added (in **bold**):
+- **powerpoint** — Generate .pptx presentations with slides, layouts, and themes
+- **word** — Create .docx documents with formatted text, tables, and images
+- **image_gen** — AI image generation via DALL-E 3 and DALL-E 2
+- **csv** — Create, read, and transform CSV files
+- **data_format** — Convert JSON ↔ YAML and validate schemas
+- **code_format** — Format Python, JavaScript, JSON, YAML code
+- **email_template** — Generate responsive HTML email templates
+- **skill_creator** — Guide for creating custom skills via API or code
+
+Each skill is a `SKILL.md` file in `agent_framework/skills/builtin/skills/` with an associated CLI script executed via `ShellTool`.
 
 ### Agent Workflow
 
 1. Agent receives user request: "Create a bar chart"
 2. Agent calls `list_skills()` → sees available skills
-3. Agent calls `load_skill("chart")` → gets chart instructions
+3. Agent calls `load_skill("chart")` → gets chart instructions from SKILL.md
 4. Agent constructs the shell command as described in the instructions
 5. Agent executes via `shell_exec` → script generates the chart
 6. Optionally calls `unload_skill("chart")` when done
 
-**More info:** See [Creating Agents Guide](docs/CREATING_AGENTS.md#skills-integration) and [skills_demo_agent.py](examples/skills_demo_agent.py)
+**More info:** See [Custom Skills Guide](docs/CUSTOM_SKILLS_GUIDE.md), [Creating Agents Guide](docs/CREATING_AGENTS.md#skills-integration) and [skills_demo_agent.py](examples/skills_demo_agent.py)
 
 ## 📝 Rich Content Capabilities (Automatic)
 
@@ -1074,135 +997,6 @@ Uncheck the "Enable rich content capabilities" checkbox when creating a session.
 ```
 ````
 
-## 🎯 All Together: Complete Multi-Skills Agent
-
-Here's a complete example combining all features - MCP, off-the-shelf tools, custom tools, and format support:
-
-```python
-import os
-from typing import List, Any, Dict
-from agent_framework import LlamaIndexAgent, create_basic_agent_server
-from agent_framework.storage.file_system_management import FileStorageFactory
-from agent_framework.tools import (
-    CreateFileTool, ListFilesTool, ReadFileTool,
-    CreatePDFFromMarkdownTool, CreatePDFFromHTMLTool,
-    ChartToImageTool, MermaidToImageTool, CreatePDFWithImagesTool, TableToImageTool
-)
-from llama_index.tools.mcp import BasicMCPClient, McpToolSpec
-
-class MultiSkillsAgent(LlamaIndexAgent):
-    def __init__(self):
-        super().__init__(
-            agent_id="multi_skills_agent_v1",
-            name="Multi-Skills Agent",
-            description="A versatile assistant with file storage, PDF generation, charts, and MCP capabilities."
-        )
-        self.file_storage = None
-        self.mcp_tools = []
-        self._mcp_initialized = False
-        
-        # Off-the-shelf tools
-        self.file_tools = [
-            CreateFileTool(),
-            ListFilesTool(),
-            ReadFileTool(),
-            CreatePDFFromMarkdownTool(),
-            CreatePDFFromHTMLTool(),
-            ChartToImageTool(),
-            MermaidToImageTool(),
-            TableToImageTool(),
-            CreatePDFWithImagesTool()
-        ]
-    
-    async def _ensure_file_storage(self):
-        if self.file_storage is None:
-            self.file_storage = await FileStorageFactory.create_storage_manager()
-    
-    async def configure_session(self, session_configuration: Dict[str, Any]):
-        user_id = session_configuration.get('user_id', 'default_user')
-        session_id = session_configuration.get('session_id')
-        
-        await self._ensure_file_storage()
-        
-        # Inject context into file tools
-        for tool in self.file_tools:
-            tool.set_context(
-                file_storage=self.file_storage,
-                user_id=user_id,
-                session_id=session_id
-            )
-        
-        await super().configure_session(session_configuration)
-    
-    async def _initialize_mcp_tools(self):
-        if self._mcp_initialized:
-            return
-        
-        try:
-            from llama_index.tools.mcp import BasicMCPClient, McpToolSpec
-        except ImportError:
-            return
-        
-        # Configure MCP servers
-        mcp_configs = [
-            {
-                "command": "uvx",
-                "args": ["mcp-run-python", "stdio"]
-            }
-        ]
-        
-        for config in mcp_configs:
-            try:
-                client = BasicMCPClient(config["command"], args=config["args"])
-                mcp_tool_spec = McpToolSpec(client=client)
-                tools = await mcp_tool_spec.to_tool_list_async()
-                self.mcp_tools.extend(tools)
-            except Exception as e:
-                print(f"MCP initialization failed: {e}")
-        
-        self._mcp_initialized = True
-    
-    def get_agent_prompt(self) -> str:
-        return """You are a helpful assistant with multiple capabilities:
-        
-        - Execute Python code via MCP
-        - Create, read, and list files
-        - Generate PDF documents from markdown or HTML
-        - Create charts, mermaid diagrams, and tables
-        - Present forms and option blocks to users
-        
-        You can generate markdown, mermaid diagrams, charts, code blocks, forms and optionsblocks.
-        ALWAYS include option blocks when asking the user to select an option!
-        
-        ... See the format section above
-        """
-    
-    def get_agent_tools(self) -> List[callable]:
-        # Combine all tools
-        all_tools = []
-        all_tools.extend([tool.get_tool_function() for tool in self.file_tools])
-        all_tools.extend(self.mcp_tools)
-        return all_tools
-    
-    async def initialize_agent(self, model_name, system_prompt, tools, **kwargs):
-        await self._initialize_mcp_tools()
-        all_tools = self.get_agent_tools()
-        await super().initialize_agent(model_name, system_prompt, all_tools, **kwargs)
-
-# Start the server
-if __name__ == "__main__":
-    create_basic_agent_server(MultiSkillsAgent, port=8000)
-```
-
-**Run it:**
-```bash
-export OPENAI_API_KEY=sk-your-key
-uv run python multi_skills_agent.py
-# Open http://localhost:8000/ui
-```
-
-**Full example:** See `examples/agent_example_multi_skills.py` for the complete implementation with full format support prompt.
-
 ## 🌐 Web Interface
 
 The framework includes a built-in web UI for testing and interacting with your agent.