agentic-blocks 0.1.7__tar.gz → 0.1.8__tar.gz

{agentic_blocks-0.1.7/src/agentic_blocks.egg-info → agentic_blocks-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-blocks
-Version: 0.1.7
+Version: 0.1.8
 Summary: Simple building blocks for agentic AI systems with MCP client and conversation management
 Author-email: Magnus Bjelkenhed <bjelkenhed@gmail.com>
 License: MIT
@@ -187,66 +187,119 @@ Or pass the API key directly:
 response = call_llm(messages, api_key="your_api_key_here")
 ```
 
-## Complete Example - Agent with MCP Tools and LLM
+## Complete Example - Tool Calling with Weather API
+
+This example demonstrates a complete workflow using function calling with an LLM. For a full interactive notebook version, see `notebooks/agentic_example.ipynb`.
 
 ```python
-from agentic_blocks import MCPClient, Messages, call_llm
-
-def simple_agent():
-    # Initialize MCP client and conversation
-    client = MCPClient("https://example.com/mcp/server/sse")
-    messages = Messages(
-        system_prompt="You are a helpful research assistant.",
-        add_date_and_time=True
-    )
-    
-    # Get available tools
-    tools = client.list_tools()
-    print(f"Connected to MCP server with {len(tools)} tools")
-    
-    # Simulate user query
-    user_query = "What's the latest news about AI?"
-    messages.add_user_message(user_query)
-    
-    # Agent decides to use a search tool
-    if tools:
-        search_tool = next((t for t in tools if "search" in t["function"]["name"]), None)
-        if search_tool:
-            # Add tool call to messages
-            tool_call = {
-                "id": "search_001",
-                "type": "function",
-                "function": {
-                    "name": search_tool["function"]["name"],
-                    "arguments": '{"query": "latest AI news"}'
-                }
+from agentic_blocks import call_llm, Messages
+
+# Define tools in OpenAI function calling format
+tools = [
+    {
+        "type": "function",
+        "function": {
+            "name": "get_weather",
+            "description": "Get current weather information for a location",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "location": {
+                        "type": "string",
+                        "description": "The city and state, e.g. San Francisco, CA"
+                    },
+                    "unit": {
+                        "type": "string", 
+                        "enum": ["celsius", "fahrenheit"],
+                        "description": "Temperature unit"
+                    }
+                },
+                "required": ["location"]
             }
-            messages.add_tool_call(tool_call)
-            
-            # Execute the tool
-            result = client.call_tool(
-                search_tool["function"]["name"], 
-                {"query": "latest AI news"}
-            )
-            
-            # Add tool response
-            if result["content"]:
-                response_text = result["content"][0]["text"]
-                messages.add_tool_response("search_001", response_text)
-            
-            # Use LLM to generate response based on search results
-            messages.add_user_message("Based on the search results, please summarize the key AI news.")
-            llm_response = call_llm(messages, temperature=0.7)
-            messages.add_assistant_message(llm_response)
-    
-    # Print conversation
-    print("\\nConversation:")
-    print(messages)
-    
-    return messages.get_messages()
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "calculate",
+            "description": "Perform a mathematical calculation",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "expression": {
+                        "type": "string",
+                        "description": "Mathematical expression to evaluate"
+                    }
+                },
+                "required": ["expression"]
+            }
+        }
+    }
+]
+
+# Create conversation with system and user prompts
+messages = Messages(
+    system_prompt="You are a helpful assistant with access to weather and calculation tools.",
+    user_prompt="What is the weather in Stockholm?"
+)
+
+# Call LLM with tools - it will decide which tools to call
+model = "gpt-4o-mini"  # or your preferred model
+response = call_llm(model=model, messages=messages, tools=tools)
+
+# Add the LLM's response (including any tool calls) to conversation
+messages.add_response_message(response)
 
-if __name__ == "__main__":
-    simple_agent()
+# Display the conversation so far
+for message in messages.get_messages():
+    print(message)
+
+# Check if there are pending tool calls that need execution
+print("Has pending tool calls:", messages.has_pending_tool_calls())
+
+# In a real implementation, you would:
+# 1. Execute the actual tool calls (get_weather, calculate, etc.)
+# 2. Add tool responses using messages.add_tool_response()
+# 3. Call the LLM again to get the final user-facing response
+```
+
+**Expected Output:**
+```
+{'role': 'system', 'content': 'You are a helpful assistant with access to weather and calculation tools.'}
+{'role': 'user', 'content': 'What is the weather in Stockholm?'}
+{'role': 'assistant', 'content': '', 'tool_calls': [{'id': 'call_abc123', 'type': 'function', 'function': {'name': 'get_weather', 'arguments': '{"location": "Stockholm, Sweden", "unit": "celsius"}'}}]}
+Has pending tool calls: True
+```
+
+**Key Features Demonstrated:**
+- **Messages management**: Clean conversation history with system/user prompts
+- **Tool calling**: LLM automatically decides to call the `get_weather` function
+- **Response handling**: `add_response_message()` handles both content and tool calls
+- **Pending detection**: `has_pending_tool_calls()` identifies when tools need execution
+
+**Next Steps:**
+After the LLM makes tool calls, you would implement the actual tool functions and continue the conversation:
+
+```python
+# Implement actual weather function
+def get_weather(location, unit="celsius"):
+    # Your weather API implementation here
+    return f"The weather in {location} is sunny, 22°{unit[0].upper()}"
+
+# Execute pending tool calls
+if messages.has_pending_tool_calls():
+    last_message = messages.get_messages()[-1]
+    for tool_call in last_message.get("tool_calls", []):
+        if tool_call["function"]["name"] == "get_weather":
+            import json
+            args = json.loads(tool_call["function"]["arguments"])
+            result = get_weather(**args)
+            messages.add_tool_response(tool_call["id"], result)
+    
+    # Get final response from LLM
+    final_response = call_llm(model=model, messages=messages)
+    messages.add_assistant_message(final_response)
+    print(f"Final response: {final_response}")
 ```
 
 ## Development Principles
@@ -284,6 +337,8 @@ Messages(system_prompt=None, user_prompt=None, add_date_and_time=False)
 - `add_user_message(content: str)`: Add user message
 - `add_assistant_message(content: str)`: Add assistant message
 - `add_tool_call(tool_call: Dict)`: Add tool call to assistant message
+- `add_tool_calls(tool_calls)`: Add multiple tool calls from ChatCompletionMessageFunctionToolCall objects
+- `add_response_message(message)`: Add ChatCompletionMessage response to conversation
 - `add_tool_response(call_id: str, content: str)`: Add tool response
 - `get_messages() -> List[Dict]`: Get all messages
 - `has_pending_tool_calls() -> bool`: Check for pending tool calls

{agentic_blocks-0.1.7 → agentic_blocks-0.1.8}/README.md

@@ -154,66 +154,119 @@ Or pass the API key directly:
 response = call_llm(messages, api_key="your_api_key_here")
 ```
 
-## Complete Example - Agent with MCP Tools and LLM
+## Complete Example - Tool Calling with Weather API
+
+This example demonstrates a complete workflow using function calling with an LLM. For a full interactive notebook version, see `notebooks/agentic_example.ipynb`.
 
 ```python
-from agentic_blocks import MCPClient, Messages, call_llm
-
-def simple_agent():
-    # Initialize MCP client and conversation
-    client = MCPClient("https://example.com/mcp/server/sse")
-    messages = Messages(
-        system_prompt="You are a helpful research assistant.",
-        add_date_and_time=True
-    )
-    
-    # Get available tools
-    tools = client.list_tools()
-    print(f"Connected to MCP server with {len(tools)} tools")
-    
-    # Simulate user query
-    user_query = "What's the latest news about AI?"
-    messages.add_user_message(user_query)
-    
-    # Agent decides to use a search tool
-    if tools:
-        search_tool = next((t for t in tools if "search" in t["function"]["name"]), None)
-        if search_tool:
-            # Add tool call to messages
-            tool_call = {
-                "id": "search_001",
-                "type": "function",
-                "function": {
-                    "name": search_tool["function"]["name"],
-                    "arguments": '{"query": "latest AI news"}'
-                }
+from agentic_blocks import call_llm, Messages
+
+# Define tools in OpenAI function calling format
+tools = [
+    {
+        "type": "function",
+        "function": {
+            "name": "get_weather",
+            "description": "Get current weather information for a location",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "location": {
+                        "type": "string",
+                        "description": "The city and state, e.g. San Francisco, CA"
+                    },
+                    "unit": {
+                        "type": "string", 
+                        "enum": ["celsius", "fahrenheit"],
+                        "description": "Temperature unit"
+                    }
+                },
+                "required": ["location"]
             }
-            messages.add_tool_call(tool_call)
-            
-            # Execute the tool
-            result = client.call_tool(
-                search_tool["function"]["name"], 
-                {"query": "latest AI news"}
-            )
-            
-            # Add tool response
-            if result["content"]:
-                response_text = result["content"][0]["text"]
-                messages.add_tool_response("search_001", response_text)
-            
-            # Use LLM to generate response based on search results
-            messages.add_user_message("Based on the search results, please summarize the key AI news.")
-            llm_response = call_llm(messages, temperature=0.7)
-            messages.add_assistant_message(llm_response)
-    
-    # Print conversation
-    print("\\nConversation:")
-    print(messages)
-    
-    return messages.get_messages()
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "calculate",
+            "description": "Perform a mathematical calculation",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "expression": {
+                        "type": "string",
+                        "description": "Mathematical expression to evaluate"
+                    }
+                },
+                "required": ["expression"]
+            }
+        }
+    }
+]
+
+# Create conversation with system and user prompts
+messages = Messages(
+    system_prompt="You are a helpful assistant with access to weather and calculation tools.",
+    user_prompt="What is the weather in Stockholm?"
+)
+
+# Call LLM with tools - it will decide which tools to call
+model = "gpt-4o-mini"  # or your preferred model
+response = call_llm(model=model, messages=messages, tools=tools)
+
+# Add the LLM's response (including any tool calls) to conversation
+messages.add_response_message(response)
 
-if __name__ == "__main__":
-    simple_agent()
+# Display the conversation so far
+for message in messages.get_messages():
+    print(message)
+
+# Check if there are pending tool calls that need execution
+print("Has pending tool calls:", messages.has_pending_tool_calls())
+
+# In a real implementation, you would:
+# 1. Execute the actual tool calls (get_weather, calculate, etc.)
+# 2. Add tool responses using messages.add_tool_response()
+# 3. Call the LLM again to get the final user-facing response
+```
+
+**Expected Output:**
+```
+{'role': 'system', 'content': 'You are a helpful assistant with access to weather and calculation tools.'}
+{'role': 'user', 'content': 'What is the weather in Stockholm?'}
+{'role': 'assistant', 'content': '', 'tool_calls': [{'id': 'call_abc123', 'type': 'function', 'function': {'name': 'get_weather', 'arguments': '{"location": "Stockholm, Sweden", "unit": "celsius"}'}}]}
+Has pending tool calls: True
+```
+
+**Key Features Demonstrated:**
+- **Messages management**: Clean conversation history with system/user prompts
+- **Tool calling**: LLM automatically decides to call the `get_weather` function
+- **Response handling**: `add_response_message()` handles both content and tool calls
+- **Pending detection**: `has_pending_tool_calls()` identifies when tools need execution
+
+**Next Steps:**
+After the LLM makes tool calls, you would implement the actual tool functions and continue the conversation:
+
+```python
+# Implement actual weather function
+def get_weather(location, unit="celsius"):
+    # Your weather API implementation here
+    return f"The weather in {location} is sunny, 22°{unit[0].upper()}"
+
+# Execute pending tool calls
+if messages.has_pending_tool_calls():
+    last_message = messages.get_messages()[-1]
+    for tool_call in last_message.get("tool_calls", []):
+        if tool_call["function"]["name"] == "get_weather":
+            import json
+            args = json.loads(tool_call["function"]["arguments"])
+            result = get_weather(**args)
+            messages.add_tool_response(tool_call["id"], result)
+    
+    # Get final response from LLM
+    final_response = call_llm(model=model, messages=messages)
+    messages.add_assistant_message(final_response)
+    print(f"Final response: {final_response}")
 ```
 
 ## Development Principles
@@ -251,6 +304,8 @@ Messages(system_prompt=None, user_prompt=None, add_date_and_time=False)
 - `add_user_message(content: str)`: Add user message
 - `add_assistant_message(content: str)`: Add assistant message
 - `add_tool_call(tool_call: Dict)`: Add tool call to assistant message
+- `add_tool_calls(tool_calls)`: Add multiple tool calls from ChatCompletionMessageFunctionToolCall objects
+- `add_response_message(message)`: Add ChatCompletionMessage response to conversation
 - `add_tool_response(call_id: str, content: str)`: Add tool response
 - `get_messages() -> List[Dict]`: Get all messages
 - `has_pending_tool_calls() -> bool`: Check for pending tool calls

{agentic_blocks-0.1.7 → agentic_blocks-0.1.8}/pyproject.toml

@@ -14,7 +14,7 @@ agentic_blocks = []
 
 [project]
 name = "agentic-blocks"
-version = "0.1.7"
+version = "0.1.8"
 description = "Simple building blocks for agentic AI systems with MCP client and conversation management"
 readme = "README.md"
 requires-python = ">=3.11"

{agentic_blocks-0.1.7 → agentic_blocks-0.1.8/src/agentic_blocks.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-blocks
-Version: 0.1.7
+Version: 0.1.8
 Summary: Simple building blocks for agentic AI systems with MCP client and conversation management
 Author-email: Magnus Bjelkenhed <bjelkenhed@gmail.com>
 License: MIT
@@ -187,66 +187,119 @@ Or pass the API key directly:
 response = call_llm(messages, api_key="your_api_key_here")
 ```
 
-## Complete Example - Agent with MCP Tools and LLM
+## Complete Example - Tool Calling with Weather API
+
+This example demonstrates a complete workflow using function calling with an LLM. For a full interactive notebook version, see `notebooks/agentic_example.ipynb`.
 
 ```python
-from agentic_blocks import MCPClient, Messages, call_llm
-
-def simple_agent():
-    # Initialize MCP client and conversation
-    client = MCPClient("https://example.com/mcp/server/sse")
-    messages = Messages(
-        system_prompt="You are a helpful research assistant.",
-        add_date_and_time=True
-    )
-    
-    # Get available tools
-    tools = client.list_tools()
-    print(f"Connected to MCP server with {len(tools)} tools")
-    
-    # Simulate user query
-    user_query = "What's the latest news about AI?"
-    messages.add_user_message(user_query)
-    
-    # Agent decides to use a search tool
-    if tools:
-        search_tool = next((t for t in tools if "search" in t["function"]["name"]), None)
-        if search_tool:
-            # Add tool call to messages
-            tool_call = {
-                "id": "search_001",
-                "type": "function",
-                "function": {
-                    "name": search_tool["function"]["name"],
-                    "arguments": '{"query": "latest AI news"}'
-                }
+from agentic_blocks import call_llm, Messages
+
+# Define tools in OpenAI function calling format
+tools = [
+    {
+        "type": "function",
+        "function": {
+            "name": "get_weather",
+            "description": "Get current weather information for a location",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "location": {
+                        "type": "string",
+                        "description": "The city and state, e.g. San Francisco, CA"
+                    },
+                    "unit": {
+                        "type": "string", 
+                        "enum": ["celsius", "fahrenheit"],
+                        "description": "Temperature unit"
+                    }
+                },
+                "required": ["location"]
             }
-            messages.add_tool_call(tool_call)
-            
-            # Execute the tool
-            result = client.call_tool(
-                search_tool["function"]["name"], 
-                {"query": "latest AI news"}
-            )
-            
-            # Add tool response
-            if result["content"]:
-                response_text = result["content"][0]["text"]
-                messages.add_tool_response("search_001", response_text)
-            
-            # Use LLM to generate response based on search results
-            messages.add_user_message("Based on the search results, please summarize the key AI news.")
-            llm_response = call_llm(messages, temperature=0.7)
-            messages.add_assistant_message(llm_response)
-    
-    # Print conversation
-    print("\\nConversation:")
-    print(messages)
-    
-    return messages.get_messages()
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "calculate",
+            "description": "Perform a mathematical calculation",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "expression": {
+                        "type": "string",
+                        "description": "Mathematical expression to evaluate"
+                    }
+                },
+                "required": ["expression"]
+            }
+        }
+    }
+]
+
+# Create conversation with system and user prompts
+messages = Messages(
+    system_prompt="You are a helpful assistant with access to weather and calculation tools.",
+    user_prompt="What is the weather in Stockholm?"
+)
+
+# Call LLM with tools - it will decide which tools to call
+model = "gpt-4o-mini"  # or your preferred model
+response = call_llm(model=model, messages=messages, tools=tools)
+
+# Add the LLM's response (including any tool calls) to conversation
+messages.add_response_message(response)
 
-if __name__ == "__main__":
-    simple_agent()
+# Display the conversation so far
+for message in messages.get_messages():
+    print(message)
+
+# Check if there are pending tool calls that need execution
+print("Has pending tool calls:", messages.has_pending_tool_calls())
+
+# In a real implementation, you would:
+# 1. Execute the actual tool calls (get_weather, calculate, etc.)
+# 2. Add tool responses using messages.add_tool_response()
+# 3. Call the LLM again to get the final user-facing response
+```
+
+**Expected Output:**
+```
+{'role': 'system', 'content': 'You are a helpful assistant with access to weather and calculation tools.'}
+{'role': 'user', 'content': 'What is the weather in Stockholm?'}
+{'role': 'assistant', 'content': '', 'tool_calls': [{'id': 'call_abc123', 'type': 'function', 'function': {'name': 'get_weather', 'arguments': '{"location": "Stockholm, Sweden", "unit": "celsius"}'}}]}
+Has pending tool calls: True
+```
+
+**Key Features Demonstrated:**
+- **Messages management**: Clean conversation history with system/user prompts
+- **Tool calling**: LLM automatically decides to call the `get_weather` function
+- **Response handling**: `add_response_message()` handles both content and tool calls
+- **Pending detection**: `has_pending_tool_calls()` identifies when tools need execution
+
+**Next Steps:**
+After the LLM makes tool calls, you would implement the actual tool functions and continue the conversation:
+
+```python
+# Implement actual weather function
+def get_weather(location, unit="celsius"):
+    # Your weather API implementation here
+    return f"The weather in {location} is sunny, 22°{unit[0].upper()}"
+
+# Execute pending tool calls
+if messages.has_pending_tool_calls():
+    last_message = messages.get_messages()[-1]
+    for tool_call in last_message.get("tool_calls", []):
+        if tool_call["function"]["name"] == "get_weather":
+            import json
+            args = json.loads(tool_call["function"]["arguments"])
+            result = get_weather(**args)
+            messages.add_tool_response(tool_call["id"], result)
+    
+    # Get final response from LLM
+    final_response = call_llm(model=model, messages=messages)
+    messages.add_assistant_message(final_response)
+    print(f"Final response: {final_response}")
 ```
 
 ## Development Principles
@@ -284,6 +337,8 @@ Messages(system_prompt=None, user_prompt=None, add_date_and_time=False)
 - `add_user_message(content: str)`: Add user message
 - `add_assistant_message(content: str)`: Add assistant message
 - `add_tool_call(tool_call: Dict)`: Add tool call to assistant message
+- `add_tool_calls(tool_calls)`: Add multiple tool calls from ChatCompletionMessageFunctionToolCall objects
+- `add_response_message(message)`: Add ChatCompletionMessage response to conversation
 - `add_tool_response(call_id: str, content: str)`: Add tool response
 - `get_messages() -> List[Dict]`: Get all messages
 - `has_pending_tool_calls() -> bool`: Check for pending tool calls