{"id":36734508,"url":"https://github.com/lambda-feedback/chat-function-boilerplate","last_synced_at":"2026-01-12T12:17:56.180Z","repository":{"id":273711264,"uuid":"919506265","full_name":"lambda-feedback/chat-function-boilerplate","owner":"lambda-feedback","description":"Boilerplate repository for chat functions written in Python","archived":false,"fork":false,"pushed_at":"2025-10-03T08:22:41.000Z","size":70,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-03T10:25:56.067Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lambda-feedback.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-01-20T14:13:51.000Z","updated_at":"2025-10-03T08:22:44.000Z","dependencies_parsed_at":"2025-02-17T18:34:08.502Z","dependency_job_id":"325e0fa3-16f1-442f-93c3-ad5cba514d5d","html_url":"https://github.com/lambda-feedback/chat-function-boilerplate","commit_stats":null,"previous_names":["lambda-feedback/chat-function-boilerplate"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/lambda-feedback/chat-function-boilerplate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambda-feedback%2Fchat-function-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambda-feedback%2Fchat-function-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambda-feedback%2Fchat-function-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambda-feedback%2Fchat-function-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lambda-feedback","download_url":"https://codeload.github.com/lambda-feedback/chat-function-boilerplate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambda-feedback%2Fchat-function-boilerplate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28338975,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T10:58:46.209Z","status":"ssl_error","status_checked_at":"2026-01-12T10:58:42.742Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":"2026-01-12T12:17:56.109Z","updated_at":"2026-01-12T12:17:56.169Z","avatar_url":"https://github.com/lambda-feedback.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lambda Feedback Chat Function Boilerplate\n\nThis repository contains the code needed to develop a modular chatbot to be used on Lambda-Feedback platform [written in Python].\n\n## Quickstart\n\nThis chapter helps you to quickly set up a new Python chat module function using this repository.\n\n\u003e [!NOTE]\n\u003e To develop this function further, you will require the following environment variables in your `.env` file:\n```bash\n\u003e If you use OpenAI:\nOPENAI_API_KEY\nOPENAI_MODEL\n\n\u003e If you use GoogleAI:\nGOOGLE_AI_API_KEY\nGOOGLE_AI_MODEL\n```\n\n\u003e [!Note]\n\u003e If you decide to use another endpoint such as Azure or Ollama or any other, please update the github workflow files to use the right secrets and variables for testing.\n```bash\n\u003e If you use Azure-OpenAI:\nAZURE_OPENAI_API_KEY\nAZURE_OPENAI_ENDPOINT\nAZURE_OPENAI_API_VERSION\nAZURE_OPENAI_CHAT_DEPLOYMENT_NAME\nAZURE_OPENAI_EMBEDDING_3072_DEPLOYMENT\nAZURE_OPENAI_EMBEDDING_1536_DEPLOYMENT\nAZURE_OPENAI_EMBEDDING_3072_MODEL\nAZURE_OPENAI_EMBEDDING_1536_MODEL\n\n\u003e For monitoring of the LLM calls (follow instructions on how to set up on langsmith online):\nLANGCHAIN_TRACING_V2\nLANGCHAIN_ENDPOINT\nLANGCHAIN_API_KEY\nLANGCHAIN_PROJECT\n```\n\n#### 1. Create a new repository\nIn GitHub, choose Use this template \u003e Create a new repository in the repository toolbar.\n\nChoose the owner, and pick a name for the new repository.\n\n\u003e [!IMPORTANT] If you want to deploy the chat function to Lambda Feedback, make sure to choose the `Lambda Feedback` organization as the owner.\n\nSet the visibility to `Public` or `Private`.\n\n\u003e [!IMPORTANT] If you want to use GitHub deployment protection rules, make sure to set the visibility to `Public`.\n\nClick on Create repository.\n\n#### 2. Clone the new repository\nClone the new repository to your local machine using the following command:\n\n```bash\ngit clone \u003crepository-url\u003e\n```\n\n#### 3. Develop the chat function\n\nYou're ready to start developing your chat function. Head over to the [Development](#development) section to learn more.\n\n#### 4. Deploy the chat function\n\nYou will have to add your API key and LLM model name into the Github repo settings. Under `Secrets and variables/Actions`: the API key must be added as a secret and the LLM model must be added as a variable.\n\nYou must ensure the same namings as in your `.env` file. So, make sure to update the `.github/{dev and main}.yml` files with the correct parameter names. \n\nFor more information, check the section below [Deploy to Lambda Feedback](#deploy-to-lambda-feedback).\n\n#### 5. Update the README\n\nIn the `README.md` file, change the title and description so it fits the purpose of your chat function.\n\nAlso, don't forget to update or delete the Quickstart chapter from the `README.md` file after you've completed these steps.\n\n## Development\n\nYou can create your own invocation to your own agents hosted anywhere. Copy or update the `agent.py` from `src/agent/` and edit it to match your LLM agent requirements. Import the new invocation in the `module.py` file.\n\nYou agent can be based on an LLM hosted anywhere, you have available currently OpenAI, AzureOpenAI, and Ollama models but you can introduce your own API call in the `src/agent/utils/llm_factory.py`.\n\n### Prerequisites\n\n- [Docker](https://docs.docker.com/get-docker/)\n- [Python](https://www.python.org)\n\n### Repository Structure\n\n```bash\n.\n├── .github/workflows/\n│   ├── dev.yml                           # deploys the DEV function to Lambda Feedback\n│   ├── main.yml                          # deploys the STAGING and PROD functions to Lambda Feedback\n│   └── test-report.yml                   # gathers Pytest Report of function tests\n├── docs/                                 # docs for devs and users\n├── src/\n│   ├── agent/\n│   │   ├── utils/                        # utils for the agent, including the llm_factory\n│   │   ├── agent.py                      # the agent logic\n│   │   └── prompts.py                    # the system prompts defining the behaviour of the chatbot\n│   └── module.py                         \n└── tests/                                # contains all tests for the chat function\n    ├── manual_agent_requests.py          # allows testing of the docker container through API requests\n    ├── manual_agent_run.py               # allows testing of any LLM agent on a couple of example inputs\n    ├── test_index.py                     # pytests\n    └── test_module.py                    # pytests\n```\n\n\n## Testing the Chat Function\n\nTo test your function, you can run the unit tests, call the code directly through a python script, or build the respective chat function docker container locally and call it through an API request. Below you can find details on those processes.\n\n### Run Unit Tests\n\nYou can run the unit tests using `pytest`.\n\n```bash\npytest\n```\n\n### Run the Chat Script\n\nYou can run the Python function itself. Make sure to have a main function in either `src/module.py` or `index.py`.\n\n```bash\npython src/module.py\n```\n\nYou can also use the `manual_agent_run.py` script to test the agents with example inputs from Lambda Feedback questions and synthetic conversations.\n```bash\npython tests/manual_agent_run.py\n```\n\n### Calling the Docker Image Locally\n\nTo build the Docker image, run the following command:\n\n```bash\ndocker build -t llm_chat .\n```\n\n#### Running the Docker Image\n\nTo run the Docker image, use the following command:\n\n##### A. Without .env file:\n\n```bash\ndocker run -e OPENAI_API_KEY={your key} -e OPENAI_MODEL={your LLM chosen model name} -p 8080:8080 llm_chat\n```\n\n##### B. With container name (for interaction, e.g. copying file from inside the docker container):\n\n```bash\ndocker run --env-file .env -it --name my-lambda-container -p 8080:8080 llm_chat\n```\n\nThis will start the chat function and expose it on port `8080` and it will be open to be curl:\n\n```bash\ncurl --location 'http://localhost:8080/2015-03-31/functions/function/invocations' \\\n--header 'Content-Type: application/json' \\\n--data '{\"body\":\"{\\\"message\\\": \\\"hi\\\", \\\"params\\\": {\\\"conversation_id\\\": \\\"12345Test\\\", \\\"conversation_history\\\": [{\\\"type\\\": \\\"user\\\", \n```\n\n#### Call Docker Container\n##### A. Call Docker with Python Requests\n\nIn the `tests/` folder you can find the `manual_agent_requests.py` script that calls the POST URL of the running docker container. It reads any kind of input files with the expected schema. You can use this to test your curl calls of the chatbot.\n\n##### B. Call Docker Container through API request\n\nPOST URL:\n\n```bash\nhttp://localhost:8080/2015-03-31/functions/function/invocations\n```\n\nBody (stringified within body for API request):\n\n```JSON\n{\"body\":\"{\\\"message\\\": \\\"hi\\\", \\\"params\\\": {\\\"conversation_id\\\": \\\"12345Test\\\", \\\"conversation_history\\\": [{\\\"type\\\": \\\"user\\\", \\\"content\\\": \\\"hi\\\"}]}}\"}\n```\n\nBody with optional Params:\n```JSON\n{\n    \"message\":\"hi\",\n    \"params\":{\n        \"conversation_id\":\"12345Test\",\n        \"conversation_history\":[{\"type\":\"user\",\"content\":\"hi\"}],\n        \"summary\":\" \",\n        \"conversational_style\":\" \",\n        \"question_response_details\": \"\",\n        \"include_test_data\": true,\n    }\n}\n```\n\n### Deploy to Lambda Feedback\n\nDeploying the chat function to Lambda Feedback is simple and straightforward, as long as the repository is within the [Lambda Feedback organization](https://github.com/lambda-feedback).\n\nDuring development, we recommend using the **`dev`** branch. This branch will deploy a version of the function onto AWS using the [GitHub Actions Dev workflow](.github/workflows/dev.yml). After deploying, please, contact one of the Lambda Feedback admins to allow the function to be accessible onto `dev.lambdafeedback.com`.\n\n\u003e [!WARNING] The dev environment of the platform is always under use, so the platform might have beta/in-testing features that might cause unexpected issues.\n\nAfter you are pleased with the performance of your Chatbot and have configured the repository, a [GitHub Actions workflow](.github/workflows/main.yml) will automatically build and deploy the chat function to Lambda Feedback as soon as changes are pushed to the main branch of the repository. This deployment will upload the function onto `staging.lambdafeedback.com`, and will also initiate an `approval` stage for prod environment. Once you reach this stage, please contact an admin from Lambda Feedback to review the code and approve it such that the code can be accessible onto the main [Lambda Feedback platform](https://www.lambdafeedback.com/).\n\n\u003e [!NOTE] Once the deployment in the **`dev`** or **`main`** branch has been successful, share your necessary environment variables (e.g. API key and LLM model) with one of the Lambda Feedback team member.\n\n## Troubleshooting\n\n### Containerized Function Fails to Start\n\nIf your chat function is working fine when run locally, but not when containerized, there is much more to consider. Here are some common issues and solution approaches:\n\n**Run-time dependencies**\n\nMake sure that all run-time dependencies are installed in the Docker image.\n\n- Python packages: Make sure to add the dependency to the `requirements.txt` or `pyproject.toml` file, and run `pip install -r requirements.txt` or `poetry install` in the Dockerfile.\n- System packages: If you need to install system packages, add the installation command to the Dockerfile.\n- ML models: If your chat function depends on ML models, make sure to include them in the Docker image.\n- Data files: If your chat function depends on data files, make sure to include them in the Docker image.\n\n### Pull Changes from the Template Repository\n\nIf you want to pull changes from the template repository to your repository, follow these steps:\n\n1. Add the template repository as a remote:\n\n```bash\ngit remote add template https://github.com/lambda-feedback/chat-function-boilerplate.git\n```\n\n2. Fetch changes from all remotes:\n\n```bash\ngit fetch --all\n```\n\n3. Merge changes from the template repository:\n\n```bash\ngit merge template/main --allow-unrelated-histories\n```\n\n\u003e [!WARNING]\n\u003e Make sure to resolve any conflicts and keep the changes you want to keep.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flambda-feedback%2Fchat-function-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flambda-feedback%2Fchat-function-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flambda-feedback%2Fchat-function-boilerplate/lists"}