From c8340417241499a87a86c1cf4d87cf77b23ed9cb Mon Sep 17 00:00:00 2001 From: parkervg Date: Wed, 21 Feb 2024 19:58:57 -0500 Subject: [PATCH] Documentation updates --- blendsql/llms/local/_transformers.py | 6 ++- blendsql/llms/remote/_openai.py | 23 ++++++++-- docs/faq.md | 2 +- docs/reference/blenders/openai.md | 42 +++++++++++++++++++ docs/reference/blenders/transformers.md | 14 +++++++ docs/reference/execute-blendsql.md | 3 +- .../{ => ingredients}/ingredients.md | 2 +- .../{ => ingredients}/join-ingredient.md | 0 .../{ => ingredients}/map-ingredient.md | 0 .../{ => ingredients}/qa-ingredient.md | 0 mkdocs.yml | 19 +++++---- setup.py | 7 +++- 12 files changed, 102 insertions(+), 16 deletions(-) create mode 100644 docs/reference/blenders/openai.md create mode 100644 docs/reference/blenders/transformers.md rename docs/reference/{ => ingredients}/ingredients.md (96%) rename docs/reference/{ => ingredients}/join-ingredient.md (100%) rename docs/reference/{ => ingredients}/map-ingredient.md (100%) rename docs/reference/{ => ingredients}/qa-ingredient.md (100%) diff --git a/blendsql/llms/local/_transformers.py b/blendsql/llms/local/_transformers.py index f0bf02e9..7944e2e4 100644 --- a/blendsql/llms/local/_transformers.py +++ b/blendsql/llms/local/_transformers.py @@ -8,7 +8,11 @@ class TransformersLLM(LLM): - """Class for Transformers Local LLM.""" + """Class for Transformers local LLM. + + Args: + model_name_or_path: Name of the model on HuggingFace, or the path to a local model + """ def __init__(self, model_name_or_path: str, **kwargs): try: diff --git a/blendsql/llms/remote/_openai.py b/blendsql/llms/remote/_openai.py index faa26314..f8f957a3 100644 --- a/blendsql/llms/remote/_openai.py +++ b/blendsql/llms/remote/_openai.py @@ -46,14 +46,22 @@ def openai_setup() -> None: class AzureOpenaiLLM(LLM): - """Class for OpenAI LLM API.""" + """Class for Azure OpenAI LLM API. - def __init__(self, model_name_or_path: str, **kwargs): + Args: + model_name_or_path: Name of the Azure deployment to use + env: Path to directory of .env file, or to the file itself to load as a dotfile. + Should either contain the variable `OPENAI_API_KEY`, + or all of `TENANT_ID`, `CLIENT_ID`, `CLIENT_SECRET` + """ + + def __init__(self, model_name_or_path: str, env: str, **kwargs): super().__init__( model_name_or_path=model_name_or_path, tokenizer=tiktoken.encoding_for_model(model_name_or_path), requires_config=True, refresh_interval_min=30, + env=env, **kwargs ) @@ -70,14 +78,21 @@ def _setup(self, **kwargs) -> None: class OpenaiLLM(LLM): - """Class for OpenAI LLM API.""" + """Class for OpenAI LLM API. + + Args: + model_name_or_path: Name of the OpenAI model to use + env: Path to directory of .env file, or to the file itself to load as a dotfile. + Should contain the variable `OPENAI_API_KEY` + """ - def __init__(self, model_name_or_path: str, **kwargs): + def __init__(self, model_name_or_path: str, env: str, **kwargs): super().__init__( model_name_or_path=model_name_or_path, tokenizer=tiktoken.encoding_for_model(model_name_or_path), requires_config=True, refresh_interval_min=30, + env=env, **kwargs ) diff --git a/docs/faq.md b/docs/faq.md index b0133780..d45a1166 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -14,4 +14,4 @@ > ``` > BlendSQL makes sure to only pass those `team` values from rows which satisfy the condition `num_championship > 3` to the LLM. Additionally, since we assume the function is deterministic, we make a single LLM call and cache the results, despite the ingredient function being used twice. #### So I get how to write BlendSQL queries. But why would I use this over vanilla SQLite? -> Certain ingredients, like [LLMJoin](#joiningredient), will likely give seasoned SQL experts a headache at first. However, BlendSQL's real strength comes from it's use as an *intermediate representation for reasoning over structured + unstructured with LLMs*. Some examples of this can be found above [here](#more-examples-from-popular-qa-datasets). +> Certain ingredients, like [LLMJoin](reference/ingredients/join-ingredient.md), will likely give seasoned SQL experts a headache at first. However, BlendSQL's real strength comes from it's use as an *intermediate representation for reasoning over structured + unstructured with LLMs*. Some examples of this can be found [here](examples/hybridqa.md). diff --git a/docs/reference/blenders/openai.md b/docs/reference/blenders/openai.md new file mode 100644 index 00000000..695c162c --- /dev/null +++ b/docs/reference/blenders/openai.md @@ -0,0 +1,42 @@ +# OpenAI + +!!! note + + In order to use this LLM as a Blender, we expect that you have a .env file created with all auth variables. + +## OpenaiLLM + +::: blendsql.llms.remote._openai.OpenaiLLM + handler: python + show_source: false + +### Example Usage +Given the following `.env` file in the current directory: +```text +OPENAI_API_KEY=my_api_key +``` + +```python +from blendsql.llms import OpenaiLLM + +blender = OpenaiLLM("text-davinci-003", env=".") +``` +## AzureOpenaiLLM + +::: blendsql.llms.remote._openai.AzureOpenaiLLM + handler: python + show_source: false + +### Example Usage +Given the following `.env` file in the current directory: +```text +TENANT_ID=my_tenant_id +CLIENT_ID=my_client_id +CLIENT_SECRET=my_client_secret +``` + +```python +from blendsql.llms import AzureOpenaiLLM + +blender = AzureOpenaiLLM("text-davinci-003", env=".") +``` \ No newline at end of file diff --git a/docs/reference/blenders/transformers.md b/docs/reference/blenders/transformers.md new file mode 100644 index 00000000..f6fea0fa --- /dev/null +++ b/docs/reference/blenders/transformers.md @@ -0,0 +1,14 @@ +# Transformers + +## TransformersLLM + +::: blendsql.llms.local._transformers.TransformersLLM + handler: python + show_source: false + +### Example Usage +```python +from blendsql.llms import TransformersLLM + +blender = TransformersLLM("openai-community/gpt2") +``` \ No newline at end of file diff --git a/docs/reference/execute-blendsql.md b/docs/reference/execute-blendsql.md index 6d833176..e68f397d 100644 --- a/docs/reference/execute-blendsql.md +++ b/docs/reference/execute-blendsql.md @@ -1,4 +1,5 @@ -## Execute a BlendSQL Query +## blend() + ::: blendsql.blendsql.blend handler: python show_source: false diff --git a/docs/reference/ingredients.md b/docs/reference/ingredients/ingredients.md similarity index 96% rename from docs/reference/ingredients.md rename to docs/reference/ingredients/ingredients.md index 8c53f2ba..588ba530 100644 --- a/docs/reference/ingredients.md +++ b/docs/reference/ingredients/ingredients.md @@ -1,6 +1,6 @@ # Ingredients -![ingredients](../img/ +![ingredients](../../img/ /ingredients.jpg) Ingredients are at the core of a BlendSQL script. diff --git a/docs/reference/join-ingredient.md b/docs/reference/ingredients/join-ingredient.md similarity index 100% rename from docs/reference/join-ingredient.md rename to docs/reference/ingredients/join-ingredient.md diff --git a/docs/reference/map-ingredient.md b/docs/reference/ingredients/map-ingredient.md similarity index 100% rename from docs/reference/map-ingredient.md rename to docs/reference/ingredients/map-ingredient.md diff --git a/docs/reference/qa-ingredient.md b/docs/reference/ingredients/qa-ingredient.md similarity index 100% rename from docs/reference/qa-ingredient.md rename to docs/reference/ingredients/qa-ingredient.md diff --git a/mkdocs.yml b/mkdocs.yml index 92a947d1..02c1f570 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,6 +10,7 @@ theme: - scheme: default primary: white logo: img/blender.png + favicon: img/blender.png features: - content.code.copy - header.autohide @@ -22,6 +23,7 @@ markdown_extensions: - def_list - attr_list - md_in_html + - pymdownx.details - pymdownx.superfences @@ -32,7 +34,7 @@ plugins: handlers: python: options: - show_source: false + show_submodules: true - search - section-index @@ -48,12 +50,15 @@ nav: - Quickstart: quickstart.md - FAQ: faq.md - Documentation: - - blend(): reference/execute-blendsql.md + - Execute a BlendSQL Query: reference/execute-blendsql.md - Ingredients: - - reference/ingredients.md - - MapIngredient: reference/map-ingredient.md - - QAIngredient: reference/qa-ingredient.md - - JoinIngredient: reference/join-ingredient.md - - LLMs: reference/llms.md + - reference/ingredients/ingredients.md + - MapIngredient: reference/ingredients/map-ingredient.md + - QAIngredient: reference/ingredients/qa-ingredient.md + - JoinIngredient: reference/ingredients/join-ingredient.md + - Blenders: + - reference/blenders/blenders.md + - OpenAI: reference/blenders/openai.md + - Transformers: reference/blenders/transformers.md - Databases: reference/databases.md - Technical Walkthrough: reference/technical_walkthrough.md diff --git a/setup.py b/setup.py index 102af562..e8d67ad4 100644 --- a/setup.py +++ b/setup.py @@ -65,6 +65,11 @@ def find_version(*file_paths): "emoji==1.7.0", ], "test": ["pytest", "huggingface_hub"], - "docs": ["mkdocstrings", "mkdocs-section-index", "mkdocs", "mkdocs-python"], + "docs": [ + "mkdocs-material", + "mkdocstrings", + "mkdocs-section-index", + "mkdocstrings-python", + ], }, )