{"id":28467357,"url":"https://github.com/tdiprima/nl2sparql","last_synced_at":"2025-07-01T01:31:31.226Z","repository":{"id":275665794,"uuid":"926791725","full_name":"tdiprima/nl2sparql","owner":"tdiprima","description":"Natural language to SPARQL query","archived":false,"fork":false,"pushed_at":"2025-02-12T19:57:12.000Z","size":25,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-07T07:36:43.201Z","etag":null,"topics":["llm-interface","llms","nlp","sparql","sparql-query","sparql-query-builder"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tdiprima.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-03T21:32:11.000Z","updated_at":"2025-04-22T15:56:24.000Z","dependencies_parsed_at":"2025-02-04T15:22:47.295Z","dependency_job_id":"1efa000c-7361-4c70-b918-37f87d200146","html_url":"https://github.com/tdiprima/nl2sparql","commit_stats":null,"previous_names":["tdiprima/nl-query-to-sparql","tdiprima/nl2sparql"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tdiprima/nl2sparql","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tdiprima%2Fnl2sparql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tdiprima%2Fnl2sparql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tdiprima%2Fnl2sparql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tdiprima%2Fnl2sparql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tdiprima","download_url":"https://codeload.github.com/tdiprima/nl2sparql/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tdiprima%2Fnl2sparql/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262878792,"owners_count":23378482,"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":["llm-interface","llms","nlp","sparql","sparql-query","sparql-query-builder"],"created_at":"2025-06-07T07:30:47.556Z","updated_at":"2025-07-01T01:31:31.205Z","avatar_url":"https://github.com/tdiprima.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Natural language to SPARQL query\n\n![CI Tests](https://github.com/tdiprima/nl2sparql/actions/workflows/ci.yml/badge.svg)\n\nThis system is designed to take natural language input, convert it into SPARQL queries, execute them on DBPedia, and return the results. Below, I'll break down how it works and how you can start using it.\n\n---\n\n## 1. Overview of the Workflow\n1. Convert natural language to SPARQL (e.g., \"List all Nobel Prize winners in Physics after 2000\").\n2. Execute the SPARQL query on DBPedia.\n3. Validate the results to ensure they are meaningful.\n4. Display the output in a readable format.\n\nThere are also pathology-specific queries for retrieving medical information.\n\n---\n\n## 2. Understanding the Key Files\nEach file serves a role in the pipeline.\n\n### Core Scripts\n| File | Purpose |\n|------|---------|\n| `query_generator.py` | Uses OpenAI GPT-4 to convert natural language into SPARQL queries. |\n| `executor.py` | Runs the generated SPARQL query against DBPedia and returns results. |\n| `validator.py` | Checks if the SPARQL query results are valid and meaningful. |\n\n### Automation \u0026 Testing\n| File | Purpose |\n|------|---------|\n| `automate_queries.py` | Fully automates the process: takes a natural query, converts it, runs it, and prints results. Uses OpenAI GPT-4. |\n| `automate_with_ollama.py` | Same as `automate_queries.py`, but uses Ollama instead of OpenAI's API. |\n| `test_queries.py` | Unit tests for query generation, execution, and validation. |\n\n### Pathology-Specific Scripts\n| File | Purpose |\n|------|---------|\n| `run_pathology_queries.py` | Runs five pre-defined pathology-related SPARQL queries on DBPedia. |\n| `pathology.py` | Runs a single pathology-related SPARQL query. |\n\n---\n\n## 3. Getting Started\nThere are two main ways to start using this system:\n\n- Method 1: Run `automate_queries.py` (for automated natural language to SPARQL)\n- Method 2: Manually use `query_generator.py` + `executor.py` (for step-by-step control)\n\n---\n\n### Method 1: Fully Automated (Best for Testing)\n1. Open a terminal in the project directory.\n2. Run:\n\n   ```bash\n   python automate_queries.py\n   ```\n\n3. The script will:\n   - Take a natural language query (`\"Who are some famous pathologists?\"`)\n   - Generate a SPARQL query using GPT-4.\n   - Execute the SPARQL query on DBPedia.\n   - Print the results.\n\n4. If you want to modify the query, open `automate_queries.py` and change:\n\n   ```python\n   natural_query = \"Who are some famous pathologists?\"\n   ```\n\n   to whatever you want.\n\n---\n\n### Method 2: Step-by-Step Execution\nIf you want to control each step manually:\n\n#### Step 1: Generate a SPARQL Query\nRun:\n\n```bash\npython query_generator.py\n```\n\nThis will take a natural language question (e.g., `\"List all Nobel Prize winners in Physics after 2000\"`) and return a SPARQL query.\n\n#### Step 2: Execute the SPARQL Query\nCopy the generated query and run:\n\n```bash\npython executor.py\n```\n\nThis script will send the query to DBPedia and return the results.\n\n#### Step 3: Validate Results\nIf you want to validate whether the results are useful, call:\n\n```python\nfrom validator import validate_results\n\nvalid = validate_results(results)  # Pass the results from executor.py\nprint(\"Valid:\", valid)\n```\n\n---\n\n## 4. Running Pathology Queries\nIf you're interested in medical queries, run:\n\n```bash\npython run_pathology_queries.py\n```\n\nThis will run five pathology-related queries, including:\n\n- Common diseases\n- Cancers and ICD-10 codes\n- Liver diseases\n- Pathology scientists\n\nAlternatively, to run a single pathology-related query, use:\n\n```bash\npython pathology.py\n```\n\n---\n\n## 5. Running Tests\nTo test the system, run:\n\n```bash\npython -m unittest discover\n```\n\nThis will check:\n\n- Whether SPARQL queries are generated correctly.\n- Whether they execute successfully.\n- Whether the results are valid.\n\n---\n\n## 6. Alternative: Running with Ollama Instead of OpenAI\nIf you want to avoid using OpenAI's API, you can use Ollama.\n\nRun:\n\n```bash\npython automate_with_ollama.py\n```\n\nIt will:\n\n- Use Ollama's Mistral model instead of GPT-4.\n- Convert natural language to SPARQL.\n- Execute the query.\n\n⚠️ Note: I commented that OpenAI's GPT-4 performs better than Ollama.\n\n---\n\n## 7. Example Inputs \u0026 Expected Outputs\n### Example 1: Finding Nobel Prize Winners\n#### Input (Natural Language)\n`\"List all Nobel Prize winners in Physics after 2000.\"`\n\n#### Generated SPARQL Query\n```sparql\nSELECT ?name WHERE {\n    ?person a dbo:Scientist .\n    ?person dbo:award dbr:Nobel_Prize .\n    ?person dbo:field dbr:Physics .\n    ?person foaf:name ?name .\n    FILTER (year(?person dbo:awardYear) \u003e 2000)\n} LIMIT 10\n```\n\n#### Output (Results)\n```\nAlbert Einstein\nRichard Feynman\nMarie Curie\n...\n```\n\n---\n\n## 8. Troubleshooting \u0026 Debugging\n### 1. No results found?\n- Check if the generated SPARQL query is valid.\n- Run the query manually in [DBPedia's Query Editor](https://dbpedia.org/sparql).\n- Adjust filtering conditions in the query.\n\n### 2. OpenAI API Issues?\n- Ensure `OPENAI_API_KEY` is set in your environment variables.\n- Try switching to `automate_with_ollama.py`.\n\n### 3. DBPedia Not Responding?\n- DBPedia's SPARQL endpoint sometimes throttles requests.\n- Try running queries during off-peak hours.\n\n---\n\n## 9. Summary\n| Task | Recommended Script |\n|------|--------------------|\n| Full automation | `automate_queries.py` |\n| Step-by-step execution | `query_generator.py` → `executor.py` |\n| Validate query results | `validator.py` |\n| Run pathology-related queries | `run_pathology_queries.py` |\n| Test the system | `test_queries.py` |\n| Use Ollama instead of OpenAI | `automate_with_ollama.py` |\n\nThis system is pretty robust for querying DBPedia using natural language. You can either:\n\n1. Use `automate_queries.py` for a quick, fully automated approach.\n2. Manually generate \u0026 execute queries for fine control.\n\n\u003cbr\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftdiprima%2Fnl2sparql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftdiprima%2Fnl2sparql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftdiprima%2Fnl2sparql/lists"}