LlamaIndex: Refactor Text-to-SQL synopsis. Add full tutorial.

docs/conf.py

@@ -71,6 +71,10 @@
     # 429 Client Error: Too Many Requests
     r"https://www.terraform.io",
     r"https://developer.hashicorp.com",
+    # 400 Client Error: Bad Request for url
+    r"https://www.llama.com/.*",
+    # 403 Client Error: Forbidden for url
+    r"https://openai.com/index/gpt-4/.*",
 ]
 
 linkcheck_anchors_ignore_for_url += [

docs/integrate/llamaindex/index.md

@@ -13,15 +13,16 @@
 ```{div} .clearfix
 ```
 
-[LlamaIndex] is a data framework for Large Language Models (LLMs). It comes with
-pre-trained models on massive public datasets such as GPT-4 or Llama 2, and
-provides an interface to external data sources allowing for natural language
-querying on your private data.
+:::{rubric} About
+:::
+
+[LlamaIndex] is a data framework for Large Language Models (LLMs). It integrates
+with providers and models such as GPT‑4 or Llama 3/4, and provides interfaces to
+external data sources for natural‑language querying of your private data.
 
-Azure Open AI Service is a fully managed service that runs on the Azure global
-infrastructure and allows developers to integrate OpenAI models into their
-applications. Through Azure Open AI API one can easily access a wide range of
-AI models in a scalable and reliable way.
+Azure OpenAI Service runs on the Azure global infrastructure and lets you
+integrate OpenAI models into your applications. The Azure OpenAI API provides
+scalable access to a wide range of models.
 
 :::{rubric} Use case examples
 :::
@@ -31,87 +32,58 @@ What can you do with LlamaIndex?
 - [LlamaIndex: Building an Agent]
 - [LlamaIndex: Using Workflows]
 
+:::{rubric} Learn
+:::
 
-## Install
-Project dependencies. For example, use them in a `requirements.txt` file.
-```shell
-langchain-openai<0.3
-llama-index-embeddings-langchain<0.4
-llama-index-embeddings-openai<0.4
-llama-index-llms-azure-openai<0.4
-llama-index-llms-openai<0.4
-sqlalchemy-cratedb
-```
-
-## Synopsis
-
-:::{dropdown} Code example using the LlamaIndex package
-```python
-import os
-import sqlalchemy as sa
-
-from llama_index.core.utilities.sql_wrapper import SQLDatabase
-from llama_index.core.query_engine import NLSQLTableQueryEngine
-from llama_index.core import Settings
-
-engine = sa.create_engine("crate://localhost:4200/")
-engine.connect()
+::::{grid} 2
+:gutter: 2
 
-sql_database = SQLDatabase(
-    engine, 
-    include_tables=["testdrive"]
-)
+:::{grid-item-card} Synopsis: Using LlamaIndex for Text-to-SQL
+:link: llamaindex-synopsis
+:link-type: ref
+Text-to-SQL: Talk to your data using human language and
+contemporary large language models, optionally offline.
 
-query_engine = NLSQLTableQueryEngine(
-    sql_database=sql_database,
-    tables=[os.getenv("CRATEDB_TABLE_NAME")],
-    llm=Settings.llm
-)
+{tags-primary}`Fundamentals`
+{tags-secondary}`LLM`
+{tags-secondary}`NLP`
+{tags-secondary}`RAG`
+:::
 
-query_str = "What is the average value for sensor 1?"
-answer = query_engine.query(query_str)
-print(answer.get_formatted_sources())
-print("Query was:", query_str)
-print("Answer was:", answer)
+:::{grid-item-card} Demo: Using LlamaIndex with OpenAI/Azure OpenAI and CrateDB
+:link: llamaindex-tutorial
+:link-type: ref
+- Connect CrateDB to an LLM via OpenAI or Azure OpenAI.
+- Text‑to‑SQL: Query CrateDB in natural language.
 
-# query was: What is the average value for sensor 1?
-# answer was: The average value for sensor 1 is 17.03.
-```
+{tags-primary}`Cloud LLM`
+{tags-secondary}`LLM`
+{tags-secondary}`NLP`
+{tags-secondary}`RAG`
 :::
 
+:::{grid-item-card} LlamaIndex and CrateDB: Code Examples
+:link: https://github.com/crate/cratedb-examples/tree/main/topic/machine-learning/llama-index
+:link-type: url
+NL2SQL with LlamaIndex: Querying CrateDB using natural language.
 
-## Learn
-
-:::{rubric} Tutorials
+{tags-primary}`Runnable example`
 :::
 
-::::{info-card}
-:::{grid-item}
-:columns: 9
-**Demo: Using LlamaIndex with OpenAI and CrateDB**
+::::
 
-- Connect your CrateDB data to an LLM using OpenAI or Azure OpenAI.
-- Text-to-SQL / Talk to your data: Query the database in human language; query CrateDB in plain English.
 
-{hyper-tutorial}`[LlamaIndex and CrateDB: Tutorial]`
-[![README](https://img.shields.io/badge/Open-README-darkblue?logo=GitHub)][LlamaIndex and CrateDB: Code Examples]
-[![Program on GitHub](https://img.shields.io/badge/Open%20on-GitHub-darkgreen?logo=GitHub)][llamaindex-nlquery-github]
+:::{toctree}
+:maxdepth: 1
+:hidden:
+Text-to-SQL synopsis <synopsis>
+Text-to-SQL tutorial <tutorial>
 :::
-:::{grid-item}
-:columns: 3
-{tags-primary}`Fundamentals` \
-{tags-secondary}`LLM` \
-{tags-secondary}`NLP` \
-{tags-secondary}`RAG`
-:::
-::::
-
 
 
 [LlamaIndex]: https://www.llamaindex.ai/framework
 [LlamaIndex: Building a RAG pipeline]: https://docs.llamaindex.ai/en/stable/understanding/rag/
 [LlamaIndex: Building an Agent]: https://docs.llamaindex.ai/en/stable/understanding/agent/
 [LlamaIndex: Using Workflows]: https://docs.llamaindex.ai/en/stable/understanding/workflows/
 [LlamaIndex and CrateDB: Code Examples]: https://github.com/crate/cratedb-examples/tree/main/topic/machine-learning/llama-index
-[LlamaIndex and CrateDB: Tutorial]: https://community.cratedb.com/t/how-to-connect-your-cratedb-data-to-llm-with-llamaindex-and-azure-openai/1612
 [llamaindex-nlquery-github]: https://github.com/crate/cratedb-examples/blob/main/topic/machine-learning/llama-index/demo_nlsql.py

docs/integrate/llamaindex/synopsis.md

@@ -0,0 +1,155 @@
+(llamaindex-synopsis)=
+# Synopsis: Text-to-SQL with LlamaIndex
+
+:::{div} sd-text-muted
+Text-to-SQL: Talk to your data using human language and
+contemporary large language models, optionally offline.
+:::
+
+## Install
+Project dependencies. For example, use them in a `requirements.txt` file.
+```shell
+langchain-openai<0.4
+llama-index-embeddings-langchain<0.5
+llama-index-embeddings-openai<0.6
+llama-index-llms-azure-openai<0.5
+llama-index-llms-ollama<0.8
+llama-index-llms-openai<0.6
+sqlalchemy-cratedb
+```
+
+## Walkthrough
+::::{grid} 2
+:padding: 0
+:class-row: title-slim
+
+:::{grid-item}
+:columns: 4
+Import Python modules.
+:::
+:::{grid-item}
+:columns: 8
+```python
+import os
+from llama_index.llms.ollama import Ollama
+from llama_index.llms.openai import OpenAI
+from llama_index.core import SQLDatabase
+from llama_index.core.query_engine import NLSQLTableQueryEngine
+import sqlalchemy as sa
+```
+:::
+
+:::{grid-item}
+:columns: 4
+Provision an LLM using an OpenAI model.
+:::
+:::{grid-item}
+:columns: 8
+```python
+llm = OpenAI(
+    model=os.getenv("OPENAI_MODEL", "gpt-4.1"),
+    temperature=0.0,
+    api_key=os.getenv("OPENAI_API_KEY"),
+)
+```
+:::
+
+:::{grid-item}
+:columns: 4
+Alternatively, provision an LLM using a self-hosted model.
+:::
+:::{grid-item}
+:columns: 8
+```python
+llm = Ollama(
+    base_url=os.getenv("OLLAMA_BASE_URL", "http://localhost:11434"),
+    model=os.getenv("OLLAMA_MODEL", "gemma3:1b"),
+    temperature=0.0,
+    request_timeout=120.0,
+    keep_alive=-1,
+)
+```
+:::
+
+:::{grid-item}
+:columns: 4
+Connect to CrateDB.
+:::
+:::{grid-item}
+:columns: 8
+```python
+database = sa.create_engine(os.getenv("CRATEDB_SQLALCHEMY_URL", "crate://crate@localhost:4200"))
+```
+:::
+
+:::{grid-item}
+:columns: 4
+Invoke Text-to-SQL query.
+:::
+:::{grid-item}
+:columns: 8
+```python
+sql_database = SQLDatabase(engine=database)
+nlsql = NLSQLTableQueryEngine(sql_database=sql_database, llm=llm)
+answer = nlsql.query("What is the average value for sensor 1?")
+```
+:::
+
+:::{grid-item}
+:columns: 4
+Also try other languages.
+:::
+:::{grid-item}
+:columns: 8
+```python
+answer = nlsql.query("Яке середнє значення для датчика 1?")
+answer = nlsql.query("¿Cuál es el valor promedio del sensor 1?")
+answer = nlsql.query("Was ist der Durchschnittswert für Sensor 1?")
+answer = nlsql.query("Quelle est la valeur moyenne pour le capteur 1 ?")
+```
+:::
+
+::::
+
+
+## Full code example
+```python
+import os
+import sqlalchemy as sa
+
+from llama_index.core import SQLDatabase
+from llama_index.core.query_engine import NLSQLTableQueryEngine
+from llama_index.core import Settings
+
+engine = sa.create_engine("crate://localhost:4200/")
+engine.connect()
+
+sql_database = SQLDatabase(
+    engine, 
+    include_tables=["testdrive"]
+)
+
+query_engine = NLSQLTableQueryEngine(
+    sql_database=sql_database,
+    tables=[os.getenv("CRATEDB_TABLE_NAME")],
+    llm=Settings.llm
+)
+
+query_str = "What is the average value for sensor 1?"
+answer = query_engine.query(query_str)
+print(answer.get_formatted_sources())
+print("Query was:", query_str)
+print("Answer was:", answer)
+
+# query was: What is the average value for sensor 1?
+# answer was: The average value for sensor 1 is 17.03.
+```
+:::
+
+
+:::{note}
+Please find the executable example at [CrateDB Examples » llama-index].
+:::
+
+
+[CrateDB Examples » llama-index]: https://github.com/crate/cratedb-examples/tree/main/topic/machine-learning/llama-index