{"id":26795086,"url":"https://github.com/acodercat/py-calling-agent","last_synced_at":"2025-04-22T18:48:00.634Z","repository":{"id":273850038,"uuid":"921101366","full_name":"acodercat/py-calling-agent","owner":"acodercat","description":"PyCallingAgent is a tool-augmented agent framework that enables function-calling through LLM code generation and provides runtime state management.","archived":false,"fork":false,"pushed_at":"2025-03-29T12:14:00.000Z","size":39,"stargazers_count":13,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-29T12:47:37.419Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/acodercat.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-23T10:40:48.000Z","updated_at":"2025-03-29T12:17:50.000Z","dependencies_parsed_at":null,"dependency_job_id":"59114ecb-33dc-4840-9bf6-ba6bb30a22bd","html_url":"https://github.com/acodercat/py-calling-agent","commit_stats":null,"previous_names":["acodercat/pyagent","acodercat/py-calling-agent"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acodercat%2Fpy-calling-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acodercat%2Fpy-calling-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acodercat%2Fpy-calling-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acodercat%2Fpy-calling-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/acodercat","download_url":"https://codeload.github.com/acodercat/py-calling-agent/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250301661,"owners_count":21408227,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-29T17:41:37.082Z","updated_at":"2025-04-22T18:48:00.622Z","avatar_url":"https://github.com/acodercat.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🤖 PyCallingAgent\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![PyPI version](https://img.shields.io/pypi/v/py-calling-agent.svg?color=%2334D058\u0026label=pypi%20package)](https://pypi.org/project/py-calling-agent)\n\nPyCallingAgent is a tool-augmented agent framework that enables function-calling through LLM code generation and provides runtime state management. Unlike traditional JSON-schema approaches, It leverages LLM's inherent coding capabilities to interact with tools through a Python runtime environment, allowing direct access to execution results and runtime state.\n\n## Features\n\n- **Code-Based Function Calling**: Uses LLM's code generation capabilities instead of JSON schemas\n- **Runtime Environment**: \n  - Inject Python objects\n  - Register functions as tools\n  - Access execution results from runtime\n- **Multi-Turn Conversations**: Maintains context and runtime state across multiple interactions\n- **Flexible LLM Support**: Works with various LLM providers through a unified interface\n\n## Roadmap\n\nWe're actively working on expanding PyCallingAgent's capabilities, including:\n\n- Streaming response support\n- Asynchronous execution\n- Enhanced test coverage\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install py-calling-agent\n```\n\n### From Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/acodercat/py-calling-agent.git\ncd py-calling-agent\npip install -e .\n```\n\n## Example Usage\n\n### Basic Function Calling\n\n```python\nfrom py_calling_agent import PyCallingAgent, OpenAILLMEngine\n\n# Initialize LLM engine\nllm_engine = OpenAILLMEngine(\n    model_id=\"your-model\",\n    api_key=\"your-api-key\",\n    base_url=\"your-base-url\"\n)\n\n# Define tool functions\ndef add(a: int, b: int) -\u003e int:\n    \"\"\"Add two numbers together\"\"\"\n    return a + b\n\ndef multiply(a: int, b: int) -\u003e int:\n    \"\"\"Multiply two numbers together\"\"\"\n    return a * b\n\n# Create agent with functions\nagent = PyCallingAgent(\n    llm_engine,\n    functions=[add, multiply]\n)\n\n# Run calculations\nresult = agent.run(\"Calculate 5 plus 3\")\nprint(\"Result:\", result)\n```\n\n### Object Methods and State Management\n\n```python\nfrom py_calling_agent import PyCallingAgent, OpenAILLMEngine\n\n# Initialize LLM engine\nllm_engine = OpenAILLMEngine(\n    model_id=\"your-model\",\n    api_key=\"your-api-key\",\n    base_url=\"your-base-url\"\n)\n\n# Define a class with methods\nclass DataProcessor:\n    \"\"\"A utility class for processing and filtering data collections.\n    \n    This class provides methods for basic data processing operations such as\n    sorting, removing duplicates, and filtering based on thresholds.\n    \n    Example:\n        \u003e\u003e\u003e processor = DataProcessor()\n        \u003e\u003e\u003e processor.process_list([3, 1, 2, 1, 3])\n        [1, 2, 3]\n        \u003e\u003e\u003e processor.filter_numbers([1, 5, 3, 8, 2], 4)\n        [5, 8]\n    \"\"\"\n    def process_list(self, data: list) -\u003e list:\n        \"\"\"Sort a list and remove duplicates\"\"\"\n        return sorted(set(data))\n    \n    def filter_numbers(self, data: list, threshold: int) -\u003e list:\n        \"\"\"Filter numbers greater than threshold\"\"\"\n        return [x for x in data if x \u003e threshold]\n\n# Prepare context\nprocessor = DataProcessor()\nnumbers = [3, 1, 4, 1, 5, 9, 2, 6, 5]\n\nobjects = {\n    'processor': processor,\n    'numbers': numbers,\n    'processed_data': None,\n    'filtered_data': None\n}\n\nobject_descriptions = {\n    'processor': {\n        'description': 'Data processing tool with various methods',\n        'example': 'processed_data = processor.process_list(numbers)'\n    },\n    'numbers': {\n        'description': 'Input list of numbers',\n        'example': 'filtered_data = processor.filter_numbers(numbers, 5)'\n    },\n    'processed_data': {\n        'description': 'Store processed data in this variable',\n        'example': 'processed_data = processor.process_list(numbers)'\n    },\n    'filtered_data': {\n        'description': 'Store filtered data in this variable',\n        'example': 'filtered_data = processor.filter_numbers(numbers, 5)'\n    }\n}\n\n# Create agent\nagent = PyCallingAgent(\n    llm_engine,\n    objects=objects,\n    object_descriptions=object_descriptions\n)\n\n# Process data\nagent.run(\"Use processor to sort and deduplicate numbers\")\nprocessed_data = agent.get_object('processed_data')\nprint(\"Processed data:\", processed_data)\n\n# Filter data\nagent.run(\"Filter numbers greater than 4\")\nfiltered_data = agent.get_object('filtered_data')\nprint(\"Filtered data:\", filtered_data)\n```\n### Streaming Responses\n\n```python\nfrom py_calling_agent import PyCallingAgent, OpenAILLMEngine, LogLevel\n\n# Initialize LLM engine\nllm_engine = OpenAILLMEngine(\n    model_id=\"your-model\",\n    api_key=\"your-api-key\",\n    base_url=\"your-base-url\"\n)\n\n# Define tool functions\ndef calculate_sum(a: int, b: int) -\u003e int:\n    \"\"\"Calculate the sum of two numbers\"\"\"\n    return a + b\n\n# Define data processor class\nclass DataProcessor:\n    def process_list(self, data: list) -\u003e list:\n        \"\"\"Sort a list and remove duplicates\"\"\"\n        return sorted(set(data))\n\n# Prepare context\nprocessor = DataProcessor()\nnumbers = [3, 1, 4, 1, 5, 9, 2, 6, 5]\n\nobjects = {\n    'processor': processor,\n    'numbers': numbers,\n    'result': None\n}\n\nobject_descriptions = {\n    'processor': {'description': 'Data processing tool'},\n    'numbers': {'description': 'Input list of numbers'},\n    'result': {\n        'description': 'Store results here',\n        'example': 'result = processor.process_list(numbers)'\n    }\n}\n\n# Create agent with streaming support\nagent = PyCallingAgent(\n    llm_engine,\n    objects=objects,\n    object_descriptions=object_descriptions,\n    functions=[calculate_sum],\n    log_level=LogLevel.ERROR\n)\n\n# Stream the response in real-time with event type handling\nfor event in agent.stream(\"Sort the numbers and calculate sum of the first two elements\"):\n    \n    if event.type.name == 'TEXT':\n        print(event.content, end=\"\", flush=True)\n\n    if event.type.name == 'CODE':\n        print(\"Executing Code:\", event.content)\n    \n    if event.type.name == 'EXECUTION_RESULT':\n        print(\"Execution Result:\", event.content)\n    \n    if event.type.name == 'EXECUTION_ERROR':\n        print(\"Execution Error:\", event.content)\n```\n\n\n## Advanced Usage\n\nFor more examples, check out the [examples](examples) directory:\n\n- [Basic Usage](examples/basic_usage.py): Simple function calling\n- [Object State](examples/object_state.py): Managing runtime objects\n- [Object Methods](examples/object_methods.py): Using class methods\n- [Multi-Turn](examples/multi_turn.py): Complex analysis conversations\n- [Stream](examples/stream.py): Streaming responses\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a PR.\nFor more details, see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facodercat%2Fpy-calling-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Facodercat%2Fpy-calling-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facodercat%2Fpy-calling-agent/lists"}