gemini-agent-framework 0.1.0__tar.gz

gemini_agent_framework-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__
+llama.log
+localllm.exe
+.env
+llm_test

gemini_agent_framework-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: gemini-agent-framework
+Version: 0.1.0
+Summary: A framework for building agents that use Gemini's function calling capabilities
+Project-URL: Homepage, https://github.com/m7mdony/gemini-agent-framework
+Project-URL: Documentation, https://github.com/m7mdony/gemini-agent-framework#readme
+Project-URL: Repository, https://github.com/m7mdony/gemini-agent-framework.git
+Author-email: Mohamed Baathman <mohamed.baathman2001@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.8
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: requests>=2.31.0
+Description-Content-Type: text/markdown
+
+# Gemini Agent Framework
+
+A Python framework for building agents that use Gemini's function calling capabilities. This framework allows you to easily create agents that can break down complex tasks into sequential steps using available tools.
+
+## Installation
+
+```bash
+pip install gemini-agent-framework
+```
+
+## Quick Start
+
+```python
+from gemini_agent import Agent
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# Define your tools
+@Agent.description("Multiplies two numbers.")
+@Agent.parameters({
+    'a': {'type': int, 'description': 'The first number'},
+    'b': {'type': int, 'description': 'The second number'}
+})
+def multiply(a: int, b: int) -> int:
+    return a * b
+
+# Create an agent instance
+agent = Agent(api_key="your-api-key", tools=[multiply])
+
+# Use the agent
+response = agent.prompt("Multiply 3 and 7")
+print(response)  # Should output 21
+```
+
+## Features
+
+- Easy tool definition using decorators
+- Automatic sequential task breakdown
+- Support for structured responses
+- Intermediate result handling
+- Error handling and recovery
+
+## Documentation
+
+For more detailed documentation, please visit the [documentation page](https://github.com/yourusername/gemini-agent-framework#readme).
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details. 

gemini_agent_framework-0.1.0/README.md

@@ -0,0 +1,54 @@
+# Gemini Agent Framework
+
+A Python framework for building agents that use Gemini's function calling capabilities. This framework allows you to easily create agents that can break down complex tasks into sequential steps using available tools.
+
+## Installation
+
+```bash
+pip install gemini-agent-framework
+```
+
+## Quick Start
+
+```python
+from gemini_agent import Agent
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# Define your tools
+@Agent.description("Multiplies two numbers.")
+@Agent.parameters({
+    'a': {'type': int, 'description': 'The first number'},
+    'b': {'type': int, 'description': 'The second number'}
+})
+def multiply(a: int, b: int) -> int:
+    return a * b
+
+# Create an agent instance
+agent = Agent(api_key="your-api-key", tools=[multiply])
+
+# Use the agent
+response = agent.prompt("Multiply 3 and 7")
+print(response)  # Should output 21
+```
+
+## Features
+
+- Easy tool definition using decorators
+- Automatic sequential task breakdown
+- Support for structured responses
+- Intermediate result handling
+- Error handling and recovery
+
+## Documentation
+
+For more detailed documentation, please visit the [documentation page](https://github.com/yourusername/gemini-agent-framework#readme).
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details. 

gemini_agent_framework-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "gemini-agent-framework"
+version = "0.1.0"
+description = "A framework for building agents that use Gemini's function calling capabilities"
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+authors = [
+    { name = "Mohamed Baathman", email = "mohamed.baathman2001@gmail.com" }
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+]
+dependencies = [
+    "requests>=2.31.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/m7mdony/gemini-agent-framework"
+Documentation = "https://github.com/m7mdony/gemini-agent-framework#readme"
+Repository = "https://github.com/m7mdony/gemini-agent-framework.git"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gemini_agent"] 

gemini_agent_framework-0.1.0/requirements.txt

@@ -0,0 +1,2 @@
+python-dotenv>=1.0.0
+requests>=2.31.0 

gemini_agent_framework-0.1.0/src/gemini_agent/__init__.py

@@ -0,0 +1,4 @@
+from .agent import Agent
+
+__version__ = "0.1.0"
+__all__ = ["Agent"] 

gemini_agent_framework-0.1.0/src/gemini_agent/agent.py

@@ -0,0 +1,372 @@
+import requests
+import json
+import inspect
+from functools import wraps
+from typing import List, Callable, Dict, Any, Optional
+from dotenv import load_dotenv
+
+load_dotenv()
+
+class Agent:
+    PYTHON_TO_GEMINI_TYPE_MAP = {
+        str: "STRING",
+        int: "INTEGER",
+        float: "NUMBER",
+        bool: "BOOLEAN",
+        list: "ARRAY",
+        dict: "OBJECT",
+    }
+    _tools_registry: Dict[str, Dict[str, Any]] = {}  # Class-level registry
+
+    def get_gemini_type(self, py_type: type) -> str:
+        """Maps Python types to Gemini JSON schema types."""
+        return self.PYTHON_TO_GEMINI_TYPE_MAP.get(py_type, "STRING")  # Default to STRING if unknown
+
+    @staticmethod
+    def description(desc: str):
+        """Decorator to add a description to a tool function."""
+        def decorator(func):
+            if func.__name__ not in Agent._tools_registry:
+                Agent._tools_registry[func.__name__] = {}
+            Agent._tools_registry[func.__name__]['description'] = desc
+            Agent._tools_registry[func.__name__]['signature'] = inspect.signature(func)
+            Agent._tools_registry[func.__name__]['function_ref'] = func
+            @wraps(func)
+            def wrapper(*args, **kwargs):
+                return func(*args, **kwargs)
+            return wrapper
+        return decorator
+
+    @staticmethod
+    def parameters(params: Dict[str, Dict[str, Any]]):
+        """Decorator to define parameters for a tool function."""
+        def decorator(func):
+            if func.__name__ not in Agent._tools_registry:
+                Agent._tools_registry[func.__name__] = {}
+            Agent._tools_registry[func.__name__]['parameters_def'] = params
+            if 'signature' not in Agent._tools_registry[func.__name__]:
+                Agent._tools_registry[func.__name__]['signature'] = inspect.signature(func)
+            if 'function_ref' not in Agent._tools_registry[func.__name__]:
+                Agent._tools_registry[func.__name__]['function_ref'] = func
+            @wraps(func)
+            def wrapper(*args, **kwargs):
+                return func(*args, **kwargs)
+            return wrapper
+        return decorator
+
+    def __init__(self, api_key: str, tools: List[Callable] = None, model_name: str = "gemini-1.5-flash"):
+        """
+        Initializes the Agent using REST API calls.
+
+        Args:
+            api_key: Your Google Generative AI API key.
+            tools: A list of Python functions decorated as tools.
+            model_name: The name of the Gemini model to use.
+        """
+        if not api_key:
+            raise ValueError("API key is required.")
+        self.api_key = api_key
+        self.model_name = model_name
+        self.base_url = f"https://generativelanguage.googleapis.com/v1beta/models/{self.model_name}"
+        self.headers = {'Content-Type': 'application/json'}
+
+        self._registered_tools_json: List[Dict[str, Any]] = []  # Store JSON representation
+        self._tool_functions: Dict[str, Callable] = {}  # Map name to actual function
+        self._intermediate_results: Dict[str, Any] = {}  # Store intermediate results
+
+        if tools:
+            self._process_tools(tools)
+
+    def _process_tools(self, tools: List[Callable]):
+        """Converts decorated Python functions into the JSON format for the REST API."""
+        for func in tools:
+            tool_name = func.__name__
+            if tool_name not in Agent._tools_registry:
+                print(f"Warning: Function '{tool_name}' was passed but has no @Agent decorators. Skipping.")
+                continue
+
+            metadata = Agent._tools_registry[tool_name]
+            if 'description' not in metadata:
+                print(f"Warning: Function '{tool_name}' is missing @Agent.description. Skipping.")
+                continue
+
+            # Build the parameters schema JSON
+            gemini_params_schema = {
+                "type": "OBJECT",
+                "properties": {},
+                "required": []
+            }
+            params_def = metadata.get('parameters_def', {})
+            signature = metadata.get('signature')  # inspect.signature object
+
+            if not params_def and signature:
+                params_def = {}
+                for name, param in signature.parameters.items():
+                    py_type = param.annotation if param.annotation != inspect.Parameter.empty else str
+                    params_def[name] = {'type': py_type, 'description': f'Parameter {name}'}
+
+            for name, definition in params_def.items():
+                py_type = definition.get('type', str)
+                gemini_type = self.get_gemini_type(py_type)
+                gemini_params_schema["properties"][name] = {
+                    "type": gemini_type,
+                    "description": definition.get('description', '')
+                }
+                if signature and signature.parameters[name].default == inspect.Parameter.empty:
+                    gemini_params_schema["required"].append(name)
+
+            # Create the Function Declaration JSON dictionary
+            declaration_json = {
+                "name": tool_name,
+                "description": metadata['description'],
+                "parameters": gemini_params_schema if gemini_params_schema["properties"] else None
+            }
+            if declaration_json["parameters"] is None:
+                del declaration_json["parameters"]
+
+            self._registered_tools_json.append(declaration_json)
+            self._tool_functions[tool_name] = metadata['function_ref']
+
+    def _get_system_prompt(self) -> str:
+        """Returns a system prompt that guides the model in breaking down complex operations."""
+        return """You are an AI assistant that can break down complex tasks into sequential steps using available tools.
+        When faced with a complex request:
+        1. Analyze the request to identify which tools can be used
+        2. Break down the request into sequential steps
+        3. For each step:
+           - Use the most appropriate tool
+           - Store the result for use in subsequent steps
+        4. Combine the results to provide a final answer
+        
+        Available tools:
+        {tools_list}
+        
+        Remember:
+        - Always perform one operation at a time
+        - Use intermediate results from previous steps
+        - If a step requires multiple tools, execute them sequentially
+        - If you're unsure about the next step, explain your reasoning
+        """.format(tools_list="\n".join([f"- {name}: {desc}" for name, desc in 
+            [(tool['name'], tool['description']) for tool in self._registered_tools_json]]))
+
+    def _call_gemini_api(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        """Makes a POST request to the Gemini generateContent endpoint."""
+        api_url = f"{self.base_url}:generateContent?key={self.api_key}"
+        try:
+            response = requests.post(api_url, headers=self.headers, json=payload)
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            print(f"Error calling Gemini API: {e}")
+            error_message = f"API Request Error: {e}"
+            if hasattr(e, 'response') and e.response is not None:
+                try:
+                    error_details = e.response.json()
+                    error_message += f"\nDetails: {json.dumps(error_details)}"
+                except json.JSONDecodeError:
+                    error_message += f"\nResponse Body: {e.response.text}"
+            return {"error": {"message": error_message}}
+        except json.JSONDecodeError as e:
+            print(f"Error decoding Gemini API JSON response: {e}")
+            return {"error": {"message": f"JSON Decode Error: {e}"}}
+
+    def prompt(self,
+               user_prompt: str,
+               system_prompt: Optional[str] = None,
+               response_structure: Optional[Dict[str, Any]] = None,
+               conversation_history: Optional[List[Dict[str, Any]]] = None
+               ) -> Any:
+        """
+        Sends a prompt via REST API, handles function calling, and respects response structure.
+
+        Args:
+            user_prompt: The user's message.
+            system_prompt: An optional system instruction (prepended to history).
+            response_structure: An optional OpenAPI schema dict for desired output format.
+            conversation_history: Optional list of content dicts (e.g., [{'role':'user', 'parts':...}])
+
+        Returns:
+            The model's final response (string or dict/list if structured),
+            or a dictionary containing an 'error' key if something failed.
+        """
+        self._intermediate_results = {}
+        
+        if not system_prompt:
+            system_prompt = self._get_system_prompt()
+
+        current_contents = conversation_history if conversation_history else []
+        if system_prompt and not current_contents:
+            current_contents.append({'role': 'user', 'parts': [{'text': system_prompt}]})
+            current_contents.append({'role': 'model', 'parts': [{'text': "I understand I should break down complex tasks into sequential steps using the available tools."}]})
+
+        current_contents.append({'role': 'user', 'parts': [{'text': user_prompt}]})
+        payload: Dict[str, Any] = {"contents": current_contents}
+
+        if self._registered_tools_json:
+            payload["tools"] = [{"functionDeclarations": self._registered_tools_json}]
+            payload["toolConfig"] = {"functionCallingConfig": {"mode": "AUTO"}}
+
+        apply_structure_later = bool(response_structure) and bool(self._registered_tools_json)
+        final_response_schema = None
+        final_mime_type = None
+
+        if response_structure and not self._registered_tools_json:
+            apply_structure_later = False
+            payload["generationConfig"] = {
+                "response_mime_type": "application/json",
+                "response_schema": response_structure
+            }
+            final_mime_type = "application/json"
+            final_response_schema = response_structure
+
+        while True:
+            response_data = self._call_gemini_api(payload)
+
+            if "error" in response_data:
+                print(f"API call failed: {response_data['error'].get('message', 'Unknown API error')}")
+                return response_data
+
+            if not response_data.get("candidates"):
+                feedback = response_data.get("promptFeedback")
+                block_reason = feedback.get("blockReason") if feedback else "Unknown"
+                safety_ratings = feedback.get("safetyRatings") if feedback else []
+                error_msg = f"Request blocked by API. Reason: {block_reason}."
+                if safety_ratings:
+                    error_msg += f" Details: {json.dumps(safety_ratings)}"
+                print(error_msg)
+                return {"error": {"message": error_msg, "details": feedback}}
+
+            try:
+                candidate = response_data["candidates"][0]
+                content = candidate["content"]
+                
+                for part in content["parts"]:
+                    payload["contents"].append({"role": "model", "parts": [part]})
+                    
+                    if "functionCall" in part:
+                        fc = part["functionCall"]
+                        tool_name = fc["name"]
+                        args = fc.get("args", {})
+
+                        if tool_name not in self._tool_functions:
+                            error_msg = f"Model attempted to call unknown function '{tool_name}'."
+                            print(f"Error: {error_msg}")
+                            error_response_part = {
+                                "functionResponse": {
+                                    "name": tool_name,
+                                    "response": {"error": error_msg}
+                                }
+                            }
+                            payload["contents"].append({"role": "user", "parts": [error_response_part]})
+                            continue
+
+                        try:
+                            tool_function = self._tool_functions[tool_name]
+                            print(f"--- Calling Function: {tool_name}({args}) ---")
+                            
+                            for key, value in args.items():
+                                if isinstance(value, str) and value.startswith('$'):
+                                    result_key = value[1:]
+                                    if result_key in self._intermediate_results:
+                                        args[key] = self._intermediate_results[result_key]
+                            
+                            function_result = tool_function(**args)
+                            print(f"--- Function Result: {function_result} ---")
+                            
+                            result_key = f"result_{len(self._intermediate_results)}"
+                            self._intermediate_results[result_key] = function_result
+
+                            function_response_part = {
+                                "functionResponse": {
+                                    "name": tool_name,
+                                    "response": {
+                                        "content": function_result,
+                                        "result_key": result_key
+                                    }
+                                }
+                            }
+                            payload["contents"].append({"role": "user", "parts": [function_response_part]})
+
+                        except Exception as e:
+                            print(f"Error executing function {tool_name}: {e}")
+                            error_msg = f"Error during execution of tool '{tool_name}': {e}"
+                            error_response_part = {
+                                "functionResponse": {
+                                    "name": tool_name,
+                                    "response": {"error": error_msg}
+                                }
+                            }
+                            payload["contents"].append({"role": "user", "parts": [error_response_part]})
+                            continue
+
+                    elif "text" in part:
+                        final_text = part["text"]
+                        
+                        if final_mime_type == "application/json" and final_response_schema:
+                            try:
+                                structured_output = json.loads(final_text)
+                                if not any("functionCall" in p for p in content["parts"][content["parts"].index(part) + 1:]):
+                                    return structured_output
+                            except json.JSONDecodeError as e:
+                                print(f"Warning: Failed to parse initially structured output: {e}. Continuing with raw text.")
+
+                        elif apply_structure_later:
+                            if not any("functionCall" in p for p in content["parts"][content["parts"].index(part) + 1:]):
+                                print("--- Attempting final structuring call ---")
+                                formatting_payload = {
+                                    "contents": [
+                                        {"role": "user", "parts": [{"text": f"Please format the following information according to the requested JSON structure:\n\n{final_text}" }]}
+                                    ],
+                                    "generationConfig": {
+                                        "response_mime_type": "application/json",
+                                        "response_schema": response_structure
+                                    }
+                                }
+                                structured_response_data = self._call_gemini_api(formatting_payload)
+
+                                if "error" in structured_response_data:
+                                    print(f"Structuring call failed: {structured_response_data['error']}. Returning intermediate text.")
+                                    return final_text
+
+                                try:
+                                    structured_text = structured_response_data["candidates"][0]["content"]["parts"][0]["text"]
+                                    structured_output = json.loads(structured_text)
+                                    return structured_output
+                                except (KeyError, IndexError, json.JSONDecodeError) as e:
+                                    print(f"Warning: Failed to parse structured output after formatting call: {e}. Returning intermediate text.")
+                                    return final_text
+
+                        elif not any("functionCall" in p for p in content["parts"][content["parts"].index(part) + 1:]):
+                            if response_structure and not apply_structure_later:
+                                print("--- Attempting final structuring call ---")
+                                formatting_payload = {
+                                    "contents": [
+                                        {"role": "user", "parts": [{"text": f"Please format the following information according to the requested JSON structure:\n\n{final_text}" }]}
+                                    ],
+                                    "generationConfig": {
+                                        "response_mime_type": "application/json",
+                                        "response_schema": response_structure
+                                    }
+                                }
+                                structured_response_data = self._call_gemini_api(formatting_payload)
+
+                                if "error" in structured_response_data:
+                                    print(f"Structuring call failed: {structured_response_data['error']}. Returning intermediate text.")
+                                    return final_text
+
+                                try:
+                                    structured_text = structured_response_data["candidates"][0]["content"]["parts"][0]["text"]
+                                    structured_output = json.loads(structured_text)
+                                    return structured_output
+                                except (KeyError, IndexError, json.JSONDecodeError) as e:
+                                    print(f"Warning: Failed to parse structured output after formatting call: {e}. Returning intermediate text.")
+                                    return final_text
+                            return final_text
+
+                continue
+
+            except (KeyError, IndexError) as e:
+                print(f"Error parsing API response structure: {e}. Response: {response_data}")
+                return {"error": {"message": f"Error parsing API response: {e}", "details": response_data}}
+
+        return {"error": {"message": "Exited interaction loop unexpectedly."}} 

gemini_agent_framework-0.1.0/tests/test_agent.py

@@ -0,0 +1,48 @@
+import os
+from dotenv import load_dotenv
+from src.gemini_agent import Agent
+
+load_dotenv()
+
+def test_basic_operations():
+    # Define some basic math operations
+    @Agent.description("Multiplies two numbers.")
+    @Agent.parameters({
+        'a': {'type': int, 'description': 'The first number'},
+        'b': {'type': int, 'description': 'The second number'}
+    })
+    def multiply(a: int, b: int) -> int:
+        return a * b
+
+    @Agent.description("Adds two numbers.")
+    @Agent.parameters({
+        'a': {'type': int, 'description': 'The first number'},
+        'b': {'type': int, 'description': 'The second number'}
+    })
+    def add(a: int, b: int) -> int:
+        return a + b
+
+    # Create an agent with the math tools
+    agent = Agent(
+        api_key=os.getenv("GEMINI_API_KEY"),
+        tools=[multiply, add]
+    )
+
+    # Test a simple multiplication
+    response = agent.prompt("Multiply 3 and 7")
+    print(f"Multiplication result: {response}")  # Should be 21
+
+    # Test a complex operation
+    response = agent.prompt(
+        "Multiply 3 and 7, then add 4 to the result",
+        response_structure={
+            "type": "object",
+            "properties": {
+                "result": {"type": "number"}
+            }
+        }
+    )
+    print(f"Complex operation result: {response}")  # Should be {"result": 25}
+
+if __name__ == "__main__":
+    test_basic_operations()