{"id":29723400,"url":"https://github.com/jeroenvdmeer/feyod-nl2sql","last_synced_at":"2025-07-24T18:33:43.952Z","repository":{"id":291259572,"uuid":"975574294","full_name":"jeroenvdmeer/feyod-nl2sql","owner":"jeroenvdmeer","description":"Workflow for converting natural language questions about Feyenoord into executable SQL queries. Powered by LangGraph.","archived":false,"fork":false,"pushed_at":"2025-07-23T19:03:51.000Z","size":95,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-23T21:46:46.611Z","etag":null,"topics":["feyenoord","langgraph","llm","nl2sql","text2sql"],"latest_commit_sha":null,"homepage":"https://feyod.nl","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/jeroenvdmeer.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,"zenodo":null}},"created_at":"2025-04-30T14:36:04.000Z","updated_at":"2025-07-23T19:03:55.000Z","dependencies_parsed_at":"2025-05-03T13:31:30.112Z","dependency_job_id":"46ec111b-062a-482c-b0de-c1c386eacc25","html_url":"https://github.com/jeroenvdmeer/feyod-nl2sql","commit_stats":null,"previous_names":["jeroenvdmeer/feyod-common","jeroenvdmeer/feyod-nl2sql"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jeroenvdmeer/feyod-nl2sql","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeroenvdmeer%2Ffeyod-nl2sql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeroenvdmeer%2Ffeyod-nl2sql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeroenvdmeer%2Ffeyod-nl2sql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeroenvdmeer%2Ffeyod-nl2sql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jeroenvdmeer","download_url":"https://codeload.github.com/jeroenvdmeer/feyod-nl2sql/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeroenvdmeer%2Ffeyod-nl2sql/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266886571,"owners_count":24001060,"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","status":"online","status_checked_at":"2025-07-24T02:00:09.469Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["feyenoord","langgraph","llm","nl2sql","text2sql"],"created_at":"2025-07-24T18:31:52.723Z","updated_at":"2025-07-24T18:33:43.875Z","avatar_url":"https://github.com/jeroenvdmeer.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Feyenoord NL2SQL Workflow\n\nThis package provides a robust, stateful, and configurable workflow for converting natural language questions about Feyenoord into executable SQL queries. It is powered by [LangChain](https://www.langchain.com/) and [LangGraph](https://langchain-ai.github.io/langgraph/).\n\n## Overview\n\nThe core of this package is the `WorkflowManager`, a class that orchestrates a graph of nodes to process a query from start to finish. The workflow includes the following key steps:\n\n1.  **Schema Caching**: Retrieves and caches the database schema.\n2.  **Entity Resolution**: Identifies and clarifies ambiguous entities (like player or team names) in the user's query.\n3.  **SQL Generation**: Uses a powerful LLM to generate a SQL query based on the user's question and the database schema.\n4.  **Syntax Check**: Validates the generated SQL for correctness.\n5.  **Query Fixing**: If the SQL is invalid, it attempts to fix it automatically.\n6.  **Execution**: Runs the valid SQL against the database.\n7.  **Answer Formatting (Optional)**: Formats the raw database results into a natural language response.\n\n## Installation\n\nThis package is intended to be used as a local dependency. You can install it in your project's virtual environment in editable mode:\n\n```bash\npip install -e /path/to/feyod-nl2sql\n```\n\nAlternatively, you can install it directly from its Git repository:\n\n```bash\npip install git+https://github.com/jeroenvdmeer/feyod-nl2sql.git\n```\n\n## Basic Usage\n\nHere's how to use the `WorkflowManager` in your application:\n\n```python\nimport asyncio\nfrom dotenv import load_dotenv\nfrom langchain_core.messages import HumanMessage\nfrom feyod_nl2sql.workflow.manager import WorkflowManager\n\n# Load environment variables (OPENAI_API_KEY, FEYOD_DATABASE_URL)\nload_dotenv()\n\n# Configuration for the workflow\napp_config = {\n    \"FEYOD_DATABASE_URL\": os.getenv(\"FEYOD_DATABASE_URL\"),\n    \"OPENAI_API_KEY\": os.getenv(\"OPENAI_API_KEY\"),\n}\n\nasync def main():\n    # Initialize for natural language output\n    chatbot_workflow = WorkflowManager(config=app_config, format_output=True).get_graph()\n\n    # Initialize for raw data output\n    data_workflow = WorkflowManager(config=app_config, format_output=False).get_graph()\n\n    # --- Example Invocation ---\n    question = \"Hoeveel doelpunten heeft Gimenez gemaakt voor Feyenoord?\"\n    initial_state = {\"messages\": [HumanMessage(content=question)]}\n\n    # Get a natural language answer\n    final_state_chatbot = await chatbot_workflow.ainvoke(initial_state)\n    answer = final_state_chatbot[\"messages\"][-1].content\n    print(f\"Chatbot Answer: {answer}\")\n\n    # Get raw JSON data\n    final_state_data = await data_workflow.ainvoke(initial_state)\n    results = final_state_data[\"messages\"][-1].content\n    print(f\"Raw Data: {results}\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n## Configuration\n\nThe `WorkflowManager` can be initialized with a configuration dictionary. The following keys are supported:\n\n-   `FEYOD_DATABASE_URL`: The SQLAlchemy connection string for the database.\n-   `OPENAI_API_KEY`: Your OpenAI API key.\n-   `MAX_SQL_FIX_ATTEMPTS`: The maximum number of times the workflow should attempt to fix an invalid SQL query (default: 1).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeroenvdmeer%2Ffeyod-nl2sql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjeroenvdmeer%2Ffeyod-nl2sql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeroenvdmeer%2Ffeyod-nl2sql/lists"}