<!--
#!/usr/bin/python
#
# Copyright 2024 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
-->
# LogicLM: natural language data analytics
## What is LogicLM?
LogicLM is a lightweight open source natural language data analytics interface.
Vision of LogicLM: Use of predicate calculus as an intermediate representation between
natural language and data retrieval allows for reliable and efficient application of
artificial intelligence to data analysis.
LogicLM uses [Logica](https://github.com/evgskv/logica), which is an open source logic programming language.
Defining measures, dimensions and filters as predicates makes writing configuration easy and
results in a powerful OLAP query generation.
Large language models are used for translating user request formulated in natural language to
a structured config. User stays in control, since the config is displayed to the user and
can be directly edited.
## Supported back-ends
LogicLM uses Logica to generate and execute data query. Database back-ends supported by Logica are
* SQLite: lightweight in-process database that among other things comes with Python. No installation or configuration is necessary to use this back-end. Perfect for analyzing datasets up to 1GB.
* PostgreSQL: one of the most popular open-source database servers. Perfect for analyzing datasets up to 10GB.
* BigQuery: Google's distributed data warehouse capable of processing practically unlimited volumes of data.
It's a [paid product](https://cloud.google.com/bigquery/pricing), but it comes with a free tier.
To understand user's request LogicLM needs an LLM API key. Supported LLM services are: Google GenAI, OpenAI and MistralAI.
## LogicLM Configuration
You configure an instance of LogicLM describing your data cube measures, dimensions and filters.
Configuration consists of two files a Logica program and a JSON-format file.
* Logic of measures, dimensions and filtes is defined in a Logica program via rules specifying the
corresponding predicates.
* Use JSON part-of-config file to specify which predicates correspond to measures, which to dimensions and which to filters. In this file you also specify hints to the LLM, like meaning of the
measures, dimensions and some examples of answering questions.
## Configuration Examples
LogicLM repo comes with two [examples](/examples) of configurations:
* [reach](/examples/reach/): synthetic dataset for measuring reach (i.e. number of people) that were exposed to a collection of online-advertising campaigns.
* [baby_names](/examples/baby_names/): dataset about names given to babies in United States, broken by gender and state. Configuration uses BigQuery as the back-end.
## Installation
To run LogicLM clone repo and install requirements.
```
git clone https://github.com/google/logiclm
cd logiclm
python3 -m pip install -r requirements.txt
```
You will also need to install an LLM API that you would like to use, e.g. to install Google Generative AI run
```
python3 -m pip install google-generativeai
```
If you want to use BigQuery then you will need [Python SDK](https://cloud.google.com/python/docs/reference/bigquery/latest).
## Starting a UI server
Example `reach` is good for a quick start, as it uses SQLite and runs without any external database dependencies.
To enable natural language query translation you would need an LLM API key for the system that you would like to use,
i.e one of `LOGICLM_GOOGLE_GENAI_API_KEY`, `LOGICLM_OPENAI_API_KEY` or `LOGICLM_MISTRALAI_API_KEY`.
To start a LogicLM instance powered by `reach` config enter the root repo folder and run
```
export LOGICLM_GOOGLE_GENAI_API_KEY=your_key_should_be_here
python3 logiclm.py examples/reach/reach.json start_server
```
Then proceed to http://localhost:1791/.
## Programmatic usage
You can call `logiclm.py` script from command line. For example to build SQL for a natural language question use `understand_and_sql` command. If you have Google Cloud configured you can pipe the SQL to `bq` tool to query the result.
```
$ python3 logiclm.py examples/baby_names/baby_names.json understand_and_sql "What are top popular names on westcoast?" | bq query --nouse_legacy_sql
+---------+------------------+
| Name<> | NumberOfBabies<> |
+---------+------------------+
| Michael | 545822 |
| David | 475426 |
| Robert | 457956 |
+---------+------------------+
```
See `main` function in [logiclm.py](/logiclm.py) for examples of calling LogicLM library functions.
_Unless otherwise noted, the LogicLM source files are distributed under the Apache 2.0 license found in the LICENSE file._
_LogicLM is not an officially supported Google product._
Raw data
{
"_id": null,
"home_page": "https://github.com/google/LogicLM",
"name": "logiclm",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.0",
"maintainer_email": null,
"keywords": null,
"author": "Google LLC",
"author_email": "logica@evgeny.ninja",
"download_url": "https://files.pythonhosted.org/packages/af/46/d4632d4ce2aa253e3a03a51a2205b0ab20cfbf48efdd645ad658472db3dd/logiclm-1.0.1.tar.gz",
"platform": null,
"description": "<!-- \n#!/usr/bin/python\n#\n# Copyright 2024 Google LLC\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n-->\n\n# LogicLM: natural language data analytics\n\n\n\n## What is LogicLM?\n\nLogicLM is a lightweight open source natural language data analytics interface.\n\nVision of LogicLM: Use of predicate calculus as an intermediate representation between\nnatural language and data retrieval allows for reliable and efficient application of\nartificial intelligence to data analysis.\n\nLogicLM uses [Logica](https://github.com/evgskv/logica), which is an open source logic programming language.\n\nDefining measures, dimensions and filters as predicates makes writing configuration easy and\nresults in a powerful OLAP query generation.\n\nLarge language models are used for translating user request formulated in natural language to\na structured config. User stays in control, since the config is displayed to the user and\ncan be directly edited.\n\n## Supported back-ends\n\nLogicLM uses Logica to generate and execute data query. Database back-ends supported by Logica are\n\n* SQLite: lightweight in-process database that among other things comes with Python. No installation or configuration is necessary to use this back-end. Perfect for analyzing datasets up to 1GB.\n\n* PostgreSQL: one of the most popular open-source database servers. Perfect for analyzing datasets up to 10GB.\n\n* BigQuery: Google's distributed data warehouse capable of processing practically unlimited volumes of data.\nIt's a [paid product](https://cloud.google.com/bigquery/pricing), but it comes with a free tier.\n\nTo understand user's request LogicLM needs an LLM API key. Supported LLM services are: Google GenAI, OpenAI and MistralAI.\n\n## LogicLM Configuration\n\nYou configure an instance of LogicLM describing your data cube measures, dimensions and filters. \nConfiguration consists of two files a Logica program and a JSON-format file.\n\n* Logic of measures, dimensions and filtes is defined in a Logica program via rules specifying the\ncorresponding predicates. \n\n* Use JSON part-of-config file to specify which predicates correspond to measures, which to dimensions and which to filters. In this file you also specify hints to the LLM, like meaning of the \nmeasures, dimensions and some examples of answering questions.\n\n\n## Configuration Examples\n\nLogicLM repo comes with two [examples](/examples) of configurations:\n\n* [reach](/examples/reach/): synthetic dataset for measuring reach (i.e. number of people) that were exposed to a collection of online-advertising campaigns.\n\n* [baby_names](/examples/baby_names/): dataset about names given to babies in United States, broken by gender and state. Configuration uses BigQuery as the back-end.\n\n## Installation\n\nTo run LogicLM clone repo and install requirements.\n\n```\ngit clone https://github.com/google/logiclm\ncd logiclm\npython3 -m pip install -r requirements.txt\n```\n\nYou will also need to install an LLM API that you would like to use, e.g. to install Google Generative AI run\n```\npython3 -m pip install google-generativeai\n```\n\nIf you want to use BigQuery then you will need [Python SDK](https://cloud.google.com/python/docs/reference/bigquery/latest).\n\n## Starting a UI server\n\nExample `reach` is good for a quick start, as it uses SQLite and runs without any external database dependencies.\n\nTo enable natural language query translation you would need an LLM API key for the system that you would like to use,\ni.e one of `LOGICLM_GOOGLE_GENAI_API_KEY`, `LOGICLM_OPENAI_API_KEY` or `LOGICLM_MISTRALAI_API_KEY`.\n\nTo start a LogicLM instance powered by `reach` config enter the root repo folder and run\n\n```\nexport LOGICLM_GOOGLE_GENAI_API_KEY=your_key_should_be_here\npython3 logiclm.py examples/reach/reach.json start_server\n```\nThen proceed to http://localhost:1791/.\n\n## Programmatic usage\n\nYou can call `logiclm.py` script from command line. For example to build SQL for a natural language question use `understand_and_sql` command. If you have Google Cloud configured you can pipe the SQL to `bq` tool to query the result.\n\n```\n$ python3 logiclm.py examples/baby_names/baby_names.json understand_and_sql \"What are top popular names on westcoast?\" | bq query --nouse_legacy_sql\n+---------+------------------+\n| Name<> | NumberOfBabies<> |\n+---------+------------------+\n| Michael | 545822 |\n| David | 475426 |\n| Robert | 457956 |\n+---------+------------------+\n```\n\nSee `main` function in [logiclm.py](/logiclm.py) for examples of calling LogicLM library functions.\n\n\n\n_Unless otherwise noted, the LogicLM source files are distributed under the Apache 2.0 license found in the LICENSE file._\n\n_LogicLM is not an officially supported Google product._\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "LogicLM",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/google/LogicLM"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a2dbac7a7029fead295c8b752580b58790c89485305952cfc5e01c620e1dd6c7",
"md5": "d3f06b6d88eef5484ee1051b7039b309",
"sha256": "9fd675b6caa872a63a034555f8655c99225a3498a0d823dca6114cd24934e18f"
},
"downloads": -1,
"filename": "logiclm-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d3f06b6d88eef5484ee1051b7039b309",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.0",
"size": 20438,
"upload_time": "2024-05-03T19:01:04",
"upload_time_iso_8601": "2024-05-03T19:01:04.327280Z",
"url": "https://files.pythonhosted.org/packages/a2/db/ac7a7029fead295c8b752580b58790c89485305952cfc5e01c620e1dd6c7/logiclm-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "af46d4632d4ce2aa253e3a03a51a2205b0ab20cfbf48efdd645ad658472db3dd",
"md5": "6eb1456b8fdba52d410b8aed5fa4dbcc",
"sha256": "3b7c4f4cdfd7a06971f70a51a552f7eeb54ea161c319d7cce60fa773a3e1302d"
},
"downloads": -1,
"filename": "logiclm-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "6eb1456b8fdba52d410b8aed5fa4dbcc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.0",
"size": 18419,
"upload_time": "2024-05-03T19:01:05",
"upload_time_iso_8601": "2024-05-03T19:01:05.745450Z",
"url": "https://files.pythonhosted.org/packages/af/46/d4632d4ce2aa253e3a03a51a2205b0ab20cfbf48efdd645ad658472db3dd/logiclm-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-03 19:01:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "google",
"github_project": "LogicLM",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "logiclm"
}
JSON
