{"id":16939817,"url":"https://github.com/amoffat/heimdallm","last_synced_at":"2025-05-07T08:21:47.112Z","repository":{"id":177216474,"uuid":"656570421","full_name":"amoffat/HeimdaLLM","owner":"amoffat","description":"Constrain LLM output","archived":false,"fork":false,"pushed_at":"2024-07-16T17:22:23.000Z","size":3720,"stargazers_count":110,"open_issues_count":0,"forks_count":2,"subscribers_count":4,"default_branch":"dev","last_synced_at":"2025-05-02T03:41:33.249Z","etag":null,"topics":["ai","llm","sql"],"latest_commit_sha":null,"homepage":"https://heimdallm.rtfd.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amoffat.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"amoffat"}},"created_at":"2023-06-21T07:57:35.000Z","updated_at":"2025-04-08T13:57:34.000Z","dependencies_parsed_at":"2024-01-15T08:43:16.344Z","dependency_job_id":"1fc901a5-7912-4504-858d-9ac6429b0f7b","html_url":"https://github.com/amoffat/HeimdaLLM","commit_stats":null,"previous_names":["amoffat/heimdallm"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amoffat%2FHeimdaLLM","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amoffat%2FHeimdaLLM/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amoffat%2FHeimdaLLM/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amoffat%2FHeimdaLLM/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amoffat","download_url":"https://codeload.github.com/amoffat/HeimdaLLM/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252839685,"owners_count":21812149,"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":["ai","llm","sql"],"created_at":"2024-10-13T21:05:34.342Z","updated_at":"2025-05-07T08:21:47.086Z","avatar_url":"https://github.com/amoffat.png","language":"Python","funding_links":["https://github.com/sponsors/amoffat"],"categories":[],"sub_categories":[],"readme":"# HeimdaLLM\n\nPronounced `[ˈhaɪm.dɔl.əm]` or _HEIM-dall-EM_\n\nHeimdaLLM is a robust static analysis framework for validating that LLM-generated\nstructured output is safe. It currently supports SQL.\n\nIn simple terms, it helps makes sure that AI won't wreck your systems.\n\n[![Heimdall](https://raw.githubusercontent.com/amoffat/HeimdaLLM/main/docs/source/images/heimdall.png)](https://heimdallm.rtfd.io)\n[![Build status](https://github.com/amoffat/HeimdaLLM/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/amoffat/HeimdaLLM/actions)\n[![Docs](https://img.shields.io/badge/Documentation-purple.svg)](https://heimdallm.rtfd.io/)\n[![GitHub Sponsors](https://img.shields.io/github/sponsors/amoffat)](https://github.com/sponsors/amoffat)\n[![PyPI](https://img.shields.io/pypi/v/heimdallm)](https://pypi.org/project/heimdallm/)\n[![License: Commercial](https://img.shields.io/badge/License-Commercial-blue.svg)](https://forms.gle/frEPeeJx81Cmwva78)\n[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)\n[![Coverage Status](https://coveralls.io/repos/github/amoffat/HeimdaLLM/badge.svg?branch=dev)](https://coveralls.io/github/amoffat/HeimdaLLM?branch=dev)\n\nConsider the following natural-language database query:\n\n```\nhow much have i spent renting movies, broken down by month?\n```\n\nFrom this query (and a little bit of context), an LLM can produce the following SQL\nquery:\n\n```sql\nSELECT\n   strftime('%Y-%m', payment.payment_date) AS month,\n   SUM(payment.amount) AS total_amount\nFROM payment\nJOIN rental ON payment.rental_id=rental.rental_id\nJOIN customer ON payment.customer_id=customer.customer_id\nWHERE customer.customer_id=:customer_id\nGROUP BY month\nLIMIT 10;\n```\n\nBut how can you ensure the LLM-generated query is safe and that it only accesses\nauthorized data?\n\nHeimdaLLM performs static analysis on the generated SQL to ensure that only certain\ncolumns, tables, and functions are used. It also automatically edits the query to add a\n`LIMIT` and to remove forbidden columns. Lastly, it ensures that there is a column\nconstraint that would restrict the results to only the user's data.\n\nIt does all of this locally, without AI, using good ol' fashioned grammars and parsers:\n\n```\n✅ Ensuring SELECT statement...\n✅ Resolving column and table aliases...\n✅ Allowlisting selectable columns...\n   ✅ Removing 2 forbidden columns...\n✅ Ensuring correct row LIMIT exists...\n   ✅ Lowering row LIMIT to 10...\n✅ Checking JOINed tables and conditions...\n✅ Checking required WHERE conditions...\n✅ Ensuring query is constrained to requester's identity...\n✅ Allowlisting SQL functions...\n   ✅ strftime\n   ✅ SUM\n```\n\nThe validated query can then be executed:\n\n| month   | total_amount |\n| ------- | ------------ |\n| 2005-05 | 4.99         |\n| 2005-06 | 22.95        |\n| 2005-07 | 100.78       |\n| 2005-08 | 87.82        |\n\nWant to get started quickly? Go\n[here](https://heimdallm.rtfd.io/en/latest/quickstart/index.html).\n\n# 🥽 Safety\n\nI am in the process of organizing an independent security audit of HeimdaLLM. Until this\naudit is complete, I do not recommend using HeimdaLLM against any production system\nwithout a careful risk assessment. These audits are self-funded, so if you will get\nvalue from the confidence that they bring, consider [sponsoring\nme](https://github.com/sponsors/amoffat) or [inquire about interest in a commercial\nlicense](https://forms.gle/frEPeeJx81Cmwva78).\n\nTo understand some of the potential vulnerabilities, take a look at the [attack\nsurface](https://heimdallm.rtfd.io/en/latest/attack-surface.html) to see the risks and\nthe mitigations.\n\n# 📚 Database support\n\n- Sqlite\n- MySQL\n- Postgres\n\nThere is active development for the other top relational SQL databases. To help me\nprioritize, please vote on which database you would like to see supported:\n\n[![Static Badge](https://img.shields.io/badge/Vote!-here-limegreen)](https://github.com/amoffat/HeimdaLLM/discussions/2)\n\n# 📜 License\n\nHeimdaLLM is dual-licensed for open-source or for commercial use.\n\n## 🤝 Open-source license\n\nThe open-source license is [AGPLv3](https://www.gnu.org/licenses/agpl-3.0.en.html),\nwhich permits free usage, modification, and distribution, and is appropriate for\nindividual or open-source usage. For commercial usage, AGPLv3 has key obligations that\nyour organization may want to avoid:\n\n- **Source Code Disclosure:** Any changes you make and use over a network must be made\n  publicly available, potentially revealing your proprietary modifications.\n\n- **Copyleft Clause:** If HeimdaLLM is integrated into your application, the whole\n  application may need to adhere to AGPLv3 terms, including code disclosure of your\n  application.\n\n- **Service Providers:** If you use HeimdaLLM to provide services, your clients also\n  need to abide by AGPLv3, complicating contracts.\n\n## 📈 Commercial license\n\nThe commercial license eliminates the above restrictions, providing flexibility and\nprotection for your business operations. This commercial license is recommended for\ncommercial use. Please inquire about a commerical license here:\n\n[![License Inquiry](https://img.shields.io/badge/License%20inquiry-blue)](https://forms.gle/frEPeeJx81Cmwva78)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famoffat%2Fheimdallm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famoffat%2Fheimdallm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famoffat%2Fheimdallm/lists"}