{"id":15055121,"url":"https://github.com/shuyib/tool_calling_api","last_synced_at":"2025-05-16T08:32:20.409Z","repository":{"id":257737025,"uuid":"859179906","full_name":"Shuyib/tool_calling_api","owner":"Shuyib","description":"This project demonstrates function-calling with Python and Ollama, utilizing the Africa's Talking API to send airtime and messages to phone numbers using natural language prompts. Ollama + LLM w/ functions + Natural language = User Interface for non-coders.","archived":false,"fork":false,"pushed_at":"2025-05-10T08:40:28.000Z","size":556,"stargazers_count":10,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-10T09:30:30.857Z","etag":null,"topics":["africastalking-api","airtime-delivery-service","api","artificial-inteligence","autogen","automation","communication","function-calling","gradio","groq-api","llama3","llms","makefile","messaging","natural-language-preprocessing","non-coders","ollama","python","qwen2-5","user-interface"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Shuyib.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":"2024-09-18T08:18:19.000Z","updated_at":"2025-05-10T08:40:31.000Z","dependencies_parsed_at":"2024-09-18T10:57:53.140Z","dependency_job_id":"952d1e66-f19d-4f0a-8671-98da13203d73","html_url":"https://github.com/Shuyib/tool_calling_api","commit_stats":{"total_commits":45,"total_committers":2,"mean_commits":22.5,"dds":"0.11111111111111116","last_synced_commit":"792625021c6d106598e49844e39f92bf36b9d995"},"previous_names":["shuyib/tool_calling_api"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shuyib%2Ftool_calling_api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shuyib%2Ftool_calling_api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shuyib%2Ftool_calling_api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shuyib%2Ftool_calling_api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Shuyib","download_url":"https://codeload.github.com/Shuyib/tool_calling_api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254496298,"owners_count":22080689,"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":["africastalking-api","airtime-delivery-service","api","artificial-inteligence","autogen","automation","communication","function-calling","gradio","groq-api","llama3","llms","makefile","messaging","natural-language-preprocessing","non-coders","ollama","python","qwen2-5","user-interface"],"created_at":"2024-09-24T21:39:25.599Z","updated_at":"2025-05-16T08:32:20.402Z","avatar_url":"https://github.com/Shuyib.png","language":"Python","readme":"[![Agent Continuous Integration/Continuos Delivery](https://github.com/Shuyib/tool_calling_api/actions/workflows/python-app.yml/badge.svg)](https://github.com/Shuyib/tool_calling_api/blob/main/.github/workflows/python-app.yml)\n# Exploring function calling 🗣️ 🤖 🔉 with Python and ollama 🦙\nFunction-calling with Python and ollama. We are going to use the Africa's Talking API to send airtime and messages to a phone number using Natural language. Thus, creating an generative ai agent. Here are examples of prompts you can use to send airtime to a phone number:\n- Send airtime to xxxxxxxxx2046 and xxxxxxxxx3524 with an amount of 10 in currency KES\n- Send a message to xxxxxxxxx2046 and xxxxxxxxx3524 with a message \"Hello, how are you?\", using the username \"username\".\n\nNB: The phone numbers are placeholders for the actual phone numbers.\nYou need some VRAM to run this project. You can get VRAM from [here](https://vast.ai/) or [here](https://runpod.io?ref=46wgtjpg)\nWe recommend 400MB-8GB of VRAM for this project. It can run on CPU however, I recommend smaller models for this.\n\n[Mistral 7B](https://ollama.com/library/mistral), **llama 3.2 3B/1B**, [**Qwen 2.5: 0.5/1.5B**](https://ollama.com/library/qwen2.5:1.5b), [nemotron-mini 4b](https://ollama.com/library/nemotron-mini) and [llama3.1 8B](https://ollama.com/library/llama3.1) are the recommended models for this project. As for the VLM's (Vision Language Models), in the workflow consider using [llama3.2-vision](https://ollama.com/library/llama3.2-vision) or [Moondream2](https://ollama.com/library/moondream) or [olm OCR](https://huggingface.co/bartowski/allenai_olmOCR-7B-0225-preview-GGUF).        \n\nEnsure ollama is installed on your laptop/server and running before running this project. You can install ollama from [here](ollama.com)\nLearn more about tool calling \u003chttps://gorilla.cs.berkeley.edu/leaderboard.html\u003e\n\n\n## Table of contents\n- [File structure](#file-structure)\n- [Attribution](#atrribution)\n- [Installation](#installation)\n- [Run in Docker](#run-in-docker)\n- [Usage](#usage)\n- [Use cases](#use-cases)\n- [Responsible AI Practices](#responsible-ai-practices)\n- [Limitations](#limitations)\n- [Contributing](#contributing)\n- [License](#license)\n\n\n## File structure   \n.   \n├── Dockerfile.app - template to run the gradio dashboard.      \n├── Dockerfile.ollama - template to run the ollama server.   \n├── docker-compose.yml - use the ollama project and gradio dashboard.   \n├── docker-compose-codecarbon.yml - use the codecarbon project, ollama and gradio dashboard.   \n├── .env - This file contains the environment variables for the project. (Not included in the repository)   \n├── app.py - the function_call.py using gradio as the User Interface.   \n├── Makefile - This file contains the commands to run the project.   \n├── README.md - This file contains the project documentation. This is the file you are currently reading.   \n├── requirements.txt - This file contains the dependencies for the project.   \n├── requirements-dev.txt - This filee contains the dependecies for the devcontainer referencing `requirements.txt`    \n├── summary.png - How function calling works with a diagram.   \n├── tests - This directory contains the test files for the project.   \n│   ├── __init__.py - This file initializes the tests directory as a package.      \n│   ├── test_cases.py - This file contains the test cases for the project.   \n│   └── test_run.py - This file contains the code to run the test cases for the function calling LLM.   \n└── utils - This directory contains the utility files for the project.   \n│    ├── __init__.py - This file initializes the utils directory as a package.   \n│    ├── function_call.py - This file contains the code to call a function using LLMs.   \n│    └── communication_apis.py - This file contains the code to do with communication apis \u0026 experiments.   \n|    └── models.py - This file contains pydantic schemas for vision models.   \n|    └── constants.py - This file contains system prompts to adjust the model's behavior.   \n└── voice_stt_mode.py - Gradio tabbed interface with Speech-to-text interface that allows edits and a text interface.   \n\n## Attribution\n* This project uses the Qwen2.5-0.5B model developed by Alibaba Cloud under the Apache License 2.0. The original project can be found at [Qwen technical report](https://arxiv.org/abs/2412.15115)\n* Inspired by this example for the [Groq interface STT](https://github.com/bklieger-groq/gradio-groq-basics)\n* Microsoft Autogen was used to simulate multistep interactions. The original project can be found at [Microsoft Autogen](https://github.com/microsoft/autogen)\n* The project uses the Africa's Talking API to send airtime and messages to phone numbers. Check them out on this website [Africa's Talking API](https://africastalking.com/)\n* Ollama for model serving and deployment. The original project can be found at [Ollama](https://ollama.com/)\n* The project uses the Gradio library to create a user interface for the function calling LLM. The original project can be found at [Gradio](https://gradio.app/)\n* The Text-to-Speech interface uses Edge TTS by Microsoft. The original project can be found at [Edge TTS](https://github.com/rany2/edge-tts). The voice chosen is Rehema which is a voice from Tanzania.\n\n\n### License\n\nThis project is licensed under the Apache License 2.0. See the [LICENSE](./LICENSE) file for more details.\n\n## Installation\nThe project uses python 3.12. To install the project, follow the steps below:\n\n- Clone the repository\n```bash\ngit clone https://github.com/Shuyib/tool_calling_api.git\n```\n- Change directory to the project directory\n```bash\ncd tool_calling_api\n```\nCreate a virtual environment\n```bash\npython3 -m venv .venv\n```\nActivate the virtual environment\n```bash\nsource .venv/bin/activate\n```\nConfirm if steps of Makefile are working\n```bash\nmake -n\n```\n\n- Install the dependencies\n```bash\nmake install\n```\n- Run the project\n\n```bash\nmake run\n```\nLong way to run the project\n\n- Change directory to the utils directory\n```bash\ncd utils\n```\n- Run the function_call.py file\n```bash\npython function_call.py\n```\n- Run the Gradion UI instead\n```bash\npython ../app.py\n```\n\n## Run in Docker\nTo run the project in Docker, follow the steps below:\n\nNB: You'll need to have deployed ollama elsewhere as an example [here](https://vast.ai/) or [here](https://runpod.io/). Make edits to the app.py file to point to the ollama server. You can use the OpenAI SDK to interact with the ollama server. An example can be found [here](https://github.com/pooyahrtn/RunpodOllama).\n\n- Linting dockerfile\n\n```bash\nmake docker_run_test\n```\n\n- Build and run the Docker image\n\n```bash\nmake docker_run\n```\n\nNotes:\n-  The .env file contains the environment variables for the project. You can create a .env file and add the following environment variables:\n\n```bash\necho \"AT_API_KEY = yourapikey\" \u003e\u003e .env\necho \"AT_USERNAME = yourusername\" \u003e\u003e .env\necho \"GROQ_API_KEY = yourgroqapikey\" \u003e\u003e .env\necho \"LANGTRACE_API_KEY= yourlangtraceapikey\" \u003e\u003e .env\necho \"TEST_PHONE_NUMBER = yourphonenumber\" \u003e\u003e .env\necho \"TEST_PHONE_NUMBER_2 = yourphonenumber\" \u003e\u003e .env\necho \"TEST_PHONE_NUMBER_3 = yourphonenumber\" \u003e\u003e .env\n```\n- The Dockerfile creates 2 images for the ollama server and the gradio dashboard. The ollama server is running on port 11434 and the gradio dashboard is running on port 7860 . You can access the gradio dashboard by visiting \u003chttp://localhost:7860\u003e in your browser \u0026 the ollama server by visiting \u003chttp://localhost:11434\u003e in your browser. They consume about 2.72GB of storage in the container.\n- The docker-compose.yml file is used to run the ollama server and the gradio dashboard. The docker-compose-codecarbon.yml file is used to run the ollama server, the gradio dashboard and the codecarbon project.\n- You can learn more about how to make this system even more secure. Do this [course](https://www.kaggle.com/learn-guide/5-day-genai#GenAI).\n\n\n## Run in runpod.io\nMake an account if you haven't already. Once that's settled.\n\n- Click on Deploy under Pods.\n- Select the cheapest option pod to deploy for example RTX 2000 Ada.\n- This will create a jupyter lab instance.\n- Follow the Installation steps in the terminal available. Until the make install.\n- Run this command. Install ollama and serve it then redirect output to a log file.\n\n```bash\ncurl -fsSL https://ollama.com/install.sh | sh \u0026\u0026 ollama serve \u003e ollama.log 2\u003e\u00261 \u0026\n```\n- Install your preferred model in the same terminal.\n\n```bash\nollama run qwen2.5:0.5b\n```\n- Export your credentials but, if you are using a .env file, you can skip this step. It will be useful for Docker.\n\n```bash\nexport AT_API_KEY=yourapikey\nexport AT_USERNAME=yourusername\nexport GROQ_API_KEY=yourgroqapikey\nexport LANGTRACE_API_KEY=yourlangtraceapikey\nexport TEST_PHONE_NUMBER=yourphonenumber\nexport TEST_PHONE_NUMBER_2=yourphonenumber\nexport TEST_PHONE_NUMBER_3=yourphonenumber\n```\n- Continue running the installation steps in the terminal.\n- Send your first message and airtime with an LLM. 🌠\n\nRead more about setting up ollama and serveless options \u003chttps://blog.runpod.io/run-llama-3-1-405b-with-ollama-a-step-by-step-guide/\u003e \u0026 \u003chttps://blog.runpod.io/run-llama-3-1-with-vllm-on-runpod-serverless/\u003e\n\n## Usage\nThis project uses LLMs to send airtime to a phone number. The difference is that we are going to use the Africa's Talking API to send airtime to a phone number using Natural language. Here are examples of prompts you can use to send airtime to a phone number:\n- Send airtime to xxxxxxxxxx046 and xxxxxxxxxx524 with an amount of 10 in currency KES.\n- Send a message to xxxxxxxxxx046 and xxxxxxxxxx524 with a message \"Hello, how are you?\", using the username \"username\".\n\n## Updated Usage Instructions\n- The app now supports both Text and Voice input tabs.\n- In the Voice Input tab, record audio and click \"Transcribe\" to preview the transcription. Then click \"Process Edited Text\" to execute voice commands.\n- In the Text Input tab, directly type commands to send airtime or messages or to search news.\n- An autogen agent has been added to assist with generating translations to other languages. Note that this uses an evaluator-optimizer model and may not always provide accurate translations. However, this paradigm can be used for code generation, summarization, and other tasks.\n- Text-to-Speech (TTS) has been added to the app. You can listen to the output of the commands.\n\n### Responsible AI Practices\nThis project implements several responsible AI practices:\n- All test data is anonymized to protect privacy.\n- Input validation to prevent misuse (negative amounts, spam detection).\n- Handling of sensitive content and edge cases.\n- Comprehensive test coverage for various scenarios.\n- Secure handling of credentials and personal information.\n\n![Process Summary](summary.png)\n\n## Use cases\n    * Non-Technical User Interfaces: Simplifies the process for non-coders to interact with APIs, making it easier for them to send airtime and messages without needing to understand the underlying code.\n    * Customer Support Automation: Enables customer support teams to quickly send airtime or messages to clients using natural language commands, improving efficiency and response times.\n    * Marketing Campaigns: Facilitates the automation of promotional messages and airtime rewards to customers, enhancing engagement and retention.\n    * Emergency Notifications: Allows rapid dissemination of urgent alerts and notifications to a large number of recipients using simple prompts.\n    * Educational Tools: Provides a practical example for teaching how to integrate APIs with natural language processing, which can be beneficial for coding bootcamps and workshops.\n    * Multilingual Support: Supports multiple languages when sending messages and airtime, making it accessible to a diverse range of users. Testing for Arabic, French, English and Portuguese.\n\n## Limitations\n- The project is limited to sending airtime, searching for news, and messages using the Africa's Talking API. The functionality can be expanded to include other APIs and services.\n\n- The jailbreaking of the LLMS is a limitation. The LLMS are not perfect and can be manipulated to produce harmful outputs. This can be mitigated by using a secure environment and monitoring the outputs for any malicious content. However, the Best of N technique and prefix injection were effective in changing model behavior.\n\n- A small number of test cases were used to test the project. More test cases can be added to cover a wider range of scenarios and edge cases.\n\n## Contributing\nContributions are welcome. If you would like to contribute to the project, you can fork the repository, create a new branch, make your changes and then create a pull request.\n\n### Testing Guidelines\nWhen contributing, please ensure:\n- All test data uses anonymized placeholders\n- Edge cases and invalid inputs are properly tested\n- Sensitive content handling is verified\n- No real personal information is included in tests\n\n## License\n[License information](https://github.com/Shuyib/tool_calling_api/blob/main/LICENSE).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshuyib%2Ftool_calling_api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshuyib%2Ftool_calling_api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshuyib%2Ftool_calling_api/lists"}