feat: add natural language query endpoint (/api/ask)

Add NL-to-SPARQL translation using GitHub Models GPT-4o-mini with
schema-injected few-shot prompting. The /api/ask endpoint accepts
natural language questions, translates to SPARQL, validates syntax
via RDFLib, enforces safety constraints (block mutating queries,
inject LIMIT), caches results, and retries with error feedback.

- api/nl_to_sparql.py: translation module with prompt, validation, cache
- api/function_app.py: new /api/ask route alongside existing /api/sparql
- api/requirements.txt: add openai>=1.0
- tests/test_nl_to_sparql.py: 28 tests covering validation, safety, cache, LLM mock
- README.md: document /api/ask with curl/JS/Python examples

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: lqdev

README.md

@@ -73,6 +73,58 @@ Use [[wikilinks]] to link between articles.
 
 The knowledge graph is queryable at `/api/sparql`. It accepts standard [W3C SPARQL 1.1 Protocol](https://www.w3.org/TR/sparql11-protocol/) requests and returns [SPARQL Results JSON](https://www.w3.org/TR/sparql11-results-json/).
 
+### Asking Questions in Natural Language
+
+Don't know SPARQL? Use the `/api/ask` endpoint to query the knowledge graph with plain English. It uses the same LLM (GitHub Models GPT-4o-mini) to translate your question into SPARQL, execute it, and return the results alongside the generated query.
+
+> **Note:** Requires `GITHUB_TOKEN` environment variable (or configured as an Azure Static Web Apps app setting).
+
+**cURL:**
+```bash
+curl -X POST \
+  -H "Content-Type: application/json" \
+  -d '{"question": "What entities are in the knowledge graph?"}' \
+  https://<your-swa-domain>/api/ask
+```
+
+**JavaScript:**
+```js
+const res = await fetch("/api/ask", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ question: "Which articles mention SPARQL?" }),
+});
+const data = await res.json();
+console.log("Generated SPARQL:", data.sparql);
+data.results.results.bindings.forEach(row => console.log(row));
+```
+
+**Python:**
+```python
+import requests
+
+res = requests.post(
+    "https://<your-swa-domain>/api/ask",
+    json={"question": "Find all organizations"},
+).json()
+
+print("SPARQL:", res["sparql"])
+for row in res["results"]["results"]["bindings"]:
+    print(row)
+```
+
+The response includes the generated SPARQL query so you can learn the query language as you go:
+
+```json
+{
+  "question": "What entities are in the knowledge graph?",
+  "sparql": "PREFIX schema: <https://schema.org/>\nSELECT DISTINCT ?entity ?name ?type WHERE {\n  ?entity a ?type ;\n          schema:name ?name .\n  FILTER(?type != schema:Article)\n}\nLIMIT 100",
+  "results": { "head": { "vars": ["entity", "name", "type"] }, "results": { "bindings": [...] } }
+}
+```
+
+### Querying with SPARQL Directly
+
 **From a browser** — paste the URL with a `query` parameter (URL-encoded):
 ```
 https://<your-swa-domain>/api/sparql?query=PREFIX%20schema%3A%20...
@@ -163,7 +215,7 @@ LIMIT 50
 │   ├── views/        # Precomputed JSON views
 │   ├── cache/        # Per-chunk extraction cache
 │   └── manifest.json # Build metadata
-├── api/              # Azure Function (SPARQL endpoint)
+├── api/              # Azure Function (SPARQL + NL query endpoints)
 ├── app/              # Static web app
 ├── tests/            # Test suite
 └── .github/workflows/
@@ -176,7 +228,7 @@ LIMIT 50
 | Decision | Choice | Rationale |
 |----------|--------|-----------|
 | LLM Provider | GitHub Models (free) | Zero cost, GITHUB_TOKEN auth |
-| LLM Model | `openai/gpt-4o-mini` | Best quality/limit ratio (150 req/day) |
+| NL→SPARQL | GPT-4o-mini + schema-injected few-shot | Same LLM as extraction; schema injection prevents hallucinated predicates |
 | SPARQL Engine | RDFLib | Pure Python, small footprint, built-in JSON-LD |
 | Validation | pySHACL | Standard W3C SHACL, works with RDFLib |
 | Batching | 3-5 chunks/request | Stay under 8K input token limit |

api/function_app.py

@@ -1,7 +1,8 @@
-"""Azure Function: SPARQL endpoint using RDFLib.
+"""Azure Function: SPARQL endpoint and natural language query interface.
 
 Loads all .ttl files from the graph/articles/ directory into a combined
-RDFLib Dataset, then serves SPARQL queries via HTTP GET/POST.
+RDFLib Dataset, then serves SPARQL queries via HTTP GET/POST and
+natural language questions via the /api/ask endpoint.
 """
 
 import json
@@ -13,6 +14,8 @@
 import rdflib
 from rdflib import Dataset, Graph
 
+from .nl_to_sparql import translate, validate_sparql, enforce_safety
+
 app = func.FunctionApp(http_auth_level=func.AuthLevel.ANONYMOUS)
 
 # Module-level cache: load graph once per cold start
@@ -100,3 +103,74 @@ def sparql_endpoint(req: func.HttpRequest) -> func.HttpResponse:
             status_code=400,
             mimetype="application/json",
         )
+
+
+@app.route(route="ask", methods=["GET", "POST"])
+def ask_endpoint(req: func.HttpRequest) -> func.HttpResponse:
+    """Translate a natural language question to SPARQL and execute it."""
+    # Extract question
+    question = None
+    if req.method == "GET":
+        question = req.params.get("question")
+    elif req.method == "POST":
+        content_type = req.headers.get("Content-Type", "")
+        if "application/json" in content_type:
+            try:
+                body = req.get_json()
+                question = body.get("question")
+            except ValueError:
+                pass
+        if not question:
+            question = req.params.get("question")
+
+    if not question:
+        return func.HttpResponse(
+            json.dumps({"error": "Missing 'question' parameter"}),
+            status_code=400,
+            mimetype="application/json",
+        )
+
+    # Translate to SPARQL
+    sparql, error = translate(question)
+    if error:
+        status = 502 if "rate limit" in error.lower() or "api error" in error.lower() else 400
+        return func.HttpResponse(
+            json.dumps({"error": error, "question": question}),
+            status_code=status,
+            mimetype="application/json",
+            headers={"Access-Control-Allow-Origin": "*"},
+        )
+
+    # Execute query
+    try:
+        ds = _load_dataset()
+        result = ds.query(sparql)
+        serialized = result.serialize(format="json")
+        if isinstance(serialized, bytes):
+            serialized = serialized.decode("utf-8")
+        results = json.loads(serialized)
+    except Exception as e:
+        logging.error(f"SPARQL execution error for NL query: {e}")
+        return func.HttpResponse(
+            json.dumps({
+                "error": f"Query execution failed: {str(e)}",
+                "question": question,
+                "sparql": sparql,
+            }),
+            status_code=400,
+            mimetype="application/json",
+            headers={"Access-Control-Allow-Origin": "*"},
+        )
+
+    return func.HttpResponse(
+        json.dumps({
+            "question": question,
+            "sparql": sparql,
+            "results": results,
+        }),
+        mimetype="application/json",
+        headers={
+            "Access-Control-Allow-Origin": "*",
+            "Cache-Control": "public, max-age=300",
+        },
+    )