{"id":35891904,"url":"https://github.com/FalkorDB/QueryWeaver","last_synced_at":"2026-01-15T17:00:48.895Z","repository":{"id":307657349,"uuid":"1027340108","full_name":"FalkorDB/QueryWeaver","owner":"FalkorDB","description":"An open-source Text2SQL tool that transforms natural language into SQL using graph-powered schema understanding. Ask your database questions in plain English, QueryWeaver handles the weaving.","archived":false,"fork":false,"pushed_at":"2026-01-01T15:54:17.000Z","size":5026,"stargazers_count":286,"open_issues_count":57,"forks_count":27,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-01-03T06:17:07.138Z","etag":null,"topics":["falkordb","semantic-layer","text2sql"],"latest_commit_sha":null,"homepage":"https://app.queryweaver.ai","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FalkorDB.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-27T20:21:51.000Z","updated_at":"2026-01-01T12:26:56.000Z","dependencies_parsed_at":"2025-08-01T13:39:03.987Z","dependency_job_id":"f38ce51c-b0dc-47e8-93a7-361051e5748a","html_url":"https://github.com/FalkorDB/QueryWeaver","commit_stats":null,"previous_names":["falkordb/queryweaver"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/FalkorDB/QueryWeaver","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FalkorDB%2FQueryWeaver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FalkorDB%2FQueryWeaver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FalkorDB%2FQueryWeaver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FalkorDB%2FQueryWeaver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FalkorDB","download_url":"https://codeload.github.com/FalkorDB/QueryWeaver/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FalkorDB%2FQueryWeaver/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28461801,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-15T16:51:41.290Z","status":"ssl_error","status_checked_at":"2026-01-15T16:51:10.742Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["falkordb","semantic-layer","text2sql"],"created_at":"2026-01-09T09:00:40.946Z","updated_at":"2026-01-15T17:00:48.850Z","avatar_url":"https://github.com/FalkorDB.png","language":"TypeScript","readme":"\u003cdiv align=\"center\"\u003e  \n  \u003ch1\u003eQueryWeaver\u003c/h1\u003e\n\n**REST API · MCP · Graph-powered** \n\nQueryWeaver is an **open-source Text2SQL** tool that converts plain-English questions into SQL using **graph-powered schema understanding**. It helps you ask databases natural-language questions and returns SQL and results.\n\nConnect and ask questions: [![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?\u0026logo=discord\u0026logoColor=white)](https://discord.gg/b32KEzMzce)\n\n[![Try Free](https://img.shields.io/badge/Try%20Free-FalkorDB%20Cloud-FF8101?labelColor=FDE900\u0026link=https://app.falkordb.cloud)](https://app.falkordb.cloud)\n[![Dockerhub](https://img.shields.io/docker/pulls/falkordb/queryweaver?label=Docker)](https://hub.docker.com/r/falkordb/queryweaver/)\n[![Tests](https://github.com/FalkorDB/QueryWeaver/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/FalkorDB/QueryWeaver/actions/workflows/tests.yml)\n[![Swagger UI](https://img.shields.io/badge/API-Swagger-11B48A?logo=swagger\u0026logoColor=white)](https://app.queryweaver.ai/docs)\n\u003c/div\u003e\n\n![new-qw-ui-gif](https://github.com/user-attachments/assets/87bb6a50-5bf4-4217-ad05-f99e32ed2dd0)\n\n## Get Started\n### Docker\n\u003e 💡 Recommended for evaluation purposes (Local Python or Node are not required)\n```bash\ndocker run -p 5000:5000 -it falkordb/queryweaver\n```\n\n\nLaunch: http://localhost:5000\n\n---\n\n### Use an .env file (Recommended)\n\nCreate a local `.env` by copying `.env.example` and passing it to Docker. This is the simplest way to provide all required configuration:\n\n```bash\ncp .env.example .env\n# edit .env to set your values, then:\ndocker run -p 5000:5000 --env-file .env falkordb/queryweaver\n```\n\n### Alternative: Pass individual environment variables\n\nIf you prefer to pass variables on the command line, use `-e` flags (less convenient for many variables):\n\n```bash\ndocker run -p 5000:5000 -it \\\n  -e APP_ENV=production \\\n  -e FASTAPI_SECRET_KEY=your_super_secret_key_here \\\n  -e GOOGLE_CLIENT_ID=your_google_client_id \\\n  -e GOOGLE_CLIENT_SECRET=your_google_client_secret \\\n  -e GITHUB_CLIENT_ID=your_github_client_id \\\n  -e GITHUB_CLIENT_SECRET=your_github_client_secret \\\n  -e AZURE_API_KEY=your_azure_api_key \\\n  falkordb/queryweaver\n```\n\n\u003e Note: To use OpenAI directly instead of Azure OpenAI, replace `AZURE_API_KEY` with `OPENAI_API_KEY` in the above command.\n\n\u003e For a full list of configuration options, consult `.env.example`.\n\n## MCP server: host or connect (optional)\n\nQueryWeaver includes optional support for the Model Context Protocol (MCP). You can either have QueryWeaver expose an MCP-compatible HTTP surface (so other services can call QueryWeaver as an MCP server), or configure QueryWeaver to call an external MCP server for model/context services.\n\nWhat QueryWeaver provides\n- The app registers MCP operations focused on Text2SQL flows:\n   - `list_databases`\n   - `connect_database`\n   - `database_schema`\n   - `query_database`\n\n- To disable the built-in MCP endpoints set `DISABLE_MCP=true` in your `.env` or environment (default: MCP enabled).\n- Configuration\n\n- `DISABLE_MCP` — disable QueryWeaver's built-in MCP HTTP surface. Set to `true` to disable. Default: `false` (MCP enabled).\n\nExamples\n\nDisable the built-in MCP when running with Docker:\n\n```bash\ndocker run -p 5000:5000 -it --env DISABLE_MCP=true falkordb/queryweaver\n```\nCalling the built-in MCP endpoints (example)\n- The MCP surface is exposed as HTTP endpoints. \n\n\n### Server Configuration\n\nBelow is a minimal example `mcp.json` client configuration that targets a local QueryWeaver instance exposing the MCP HTTP surface at `/mcp`.\n\n```json\n{\n   \"servers\": {\n      \"queryweaver\": {\n         \"type\": \"http\",\n         \"url\": \"http://127.0.0.1:5000/mcp\",\n         \"headers\": {\n            \"Authorization\": \"Bearer your_token_here\"\n         }\n      }\n   },\n   \"inputs\": []\n}\n```\n\n## REST API \n\n### API Documentation\n\nSwagger UI: https://app.queryweaver.ai/docs\n\nOpenAPI JSON: https://app.queryweaver.ai/openapi.json\n\n### Overview\n\nQueryWeaver exposes a small REST API for managing graphs (database schemas) and running Text2SQL queries. All endpoints that modify or access user-scoped data require authentication via a bearer token. In the browser the app uses session cookies and OAuth flows; for CLI and scripts you can use an API token (see `tokens` routes or the web UI to create one).\n\nCore endpoints\n- GET /graphs — list available graphs for the authenticated user\n- GET /graphs/{graph_id}/data — return nodes/links (tables, columns, foreign keys) for the graph\n- POST /graphs — upload or create a graph (JSON payload or file upload)\n- POST /graphs/{graph_id} — run a Text2SQL chat query against the named graph (streaming response)\n\nAuthentication\n- Add an Authorization header: `Authorization: Bearer \u003cAPI_TOKEN\u003e`\n\nExamples\n\n1) List graphs (GET)\n\ncurl example:\n\n```bash\ncurl -s -H \"Authorization: Bearer $TOKEN\" \\\n   https://app.queryweaver.ai/graphs\n```\n\nPython example:\n\n```python\nimport requests\nresp = requests.get('https://app.queryweaver.ai/graphs', headers={'Authorization': f'Bearer {TOKEN}'})\nprint(resp.json())\n```\n\n2) Get graph schema (GET)\n\ncurl example:\n\n```bash\ncurl -s -H \"Authorization: Bearer $TOKEN\" \\\n   https://app.queryweaver.ai/graphs/my_database/data\n```\n\nPython example:\n\n```python\nresp = requests.get('https://app.queryweaver.ai/graphs/my_database/data', headers={'Authorization': f'Bearer {TOKEN}'})\nprint(resp.json())\n```\n\n3) Load a graph (POST) — JSON payload\n\n```bash\ncurl -H \"Authorization: Bearer $TOKEN\" -H \"Content-Type: application/json\" \\\n   -d '{\"database\": \"my_database\", \"tables\": [...]}' \\\n   https://app.queryweaver.ai/graphs\n```\n\nOr upload a file (multipart/form-data):\n\n```bash\ncurl -H \"Authorization: Bearer $TOKEN\" -F \"file=@schema.json\" \\\n   https://app.queryweaver.ai/graphs\n```\n\n4) Query a graph (POST) — run a chat-based Text2SQL request\n\nThe `POST /graphs/{graph_id}` endpoint accepts a JSON body with at least a `chat` field (an array of messages). The endpoint streams processing steps and the final SQL back as server-sent-message chunks delimited by a special boundary used by the frontend. For simple scripting you can call it and read the final JSON object from the streamed messages.\n\nExample payload:\n\n```json\n{\n   \"chat\": [\"How many users signed up last month?\"],\n   \"result\": [],\n   \"instructions\": \"Prefer PostgreSQL compatible SQL\"\n}\n```\n\ncurl example (simple, collects whole response):\n\n```bash\ncurl -s -H \"Authorization: Bearer $TOKEN\" -H \"Content-Type: application/json\" \\\n   -d '{\"chat\": [\"Count orders last week\"]}' \\\n   https://app.queryweaver.ai/graphs/my_database\n```\n\nPython example (stream-aware):\n\n```python\nimport requests\nimport json\n\nurl = 'https://app.queryweaver.ai/graphs/my_database'\nheaders = {'Authorization': f'Bearer {TOKEN}', 'Content-Type': 'application/json'}\nwith requests.post(url, headers=headers, json={\"chat\": [\"Count orders last week\"]}, stream=True) as r:\n      # The server yields JSON objects delimited by a message boundary string\n      boundary = '|||FALKORDB_MESSAGE_BOUNDARY|||'\n      buffer = ''\n      for chunk in r.iter_content(decode_unicode=True, chunk_size=1024):\n            buffer += chunk\n            while boundary in buffer:\n                  part, buffer = buffer.split(boundary, 1)\n                  if not part.strip():\n                        continue\n                  obj = json.loads(part)\n                  print('STREAM:', obj)\n\nNotes \u0026 tips\n- Graph IDs are namespaced per-user. When calling the API directly use the plain graph id (the server will namespace by the authenticated user). For uploaded files the `database` field determines the saved graph id.\n- The streaming response includes intermediate reasoning steps, follow-up questions (if the query is ambiguous or off-topic), and the final SQL. The frontend expects the boundary string `|||FALKORDB_MESSAGE_BOUNDARY|||` between messages.\n- For destructive SQL (INSERT/UPDATE/DELETE etc) the service will include a confirmation step in the stream; the frontend handles this flow. If you automate destructive operations, ensure you handle confirmation properly (see the `ConfirmRequest` model in the code).\n\n\n## Development\n\nFollow these steps to run and develop QueryWeaver from source.\n\n### Prerequisites\n\n- Python 3.12+\n- pipenv\n- A FalkorDB instance (local or remote)\n- Node.js and npm (for the React frontend)\n\n### Install and configure\n\nQuickstart (recommended for development):\n\n```bash\n# Clone the repo\ngit clone https://github.com/FalkorDB/QueryWeaver.git\ncd QueryWeaver\n\n# Install dependencies (backend + frontend) and start the dev server\nmake install\nmake run-dev\n```\n\nIf you prefer to set up manually or need a custom environment, use Pipenv:\n\n```bash\n# Install Python (backend) and frontend dependencies\npipenv sync --dev\n\n# Create a local environment file\ncp .env.example .env\n# Edit .env with your values (set APP_ENV=development for local development)\n```\n\n### Run the app locally\n\n```bash\npipenv run uvicorn api.index:app --host 0.0.0.0 --port 5000 --reload\n```\n\nThe server will be available at http://localhost:5000\n\nAlternatively, the repository provides Make targets for running the app:\n\n```bash\nmake run-dev   # development server (reload, debug-friendly)\nmake run-prod  # production mode (ensure frontend build if needed)\n```\n\n### Frontend build (when needed)\n\nThe frontend is a modern React + Vite app in `app/`. Build before production runs or after frontend changes:\n\n```bash\nmake install       # installs backend and frontend deps\nmake build-prod    # builds the frontend into app/dist/\n\n# or manually\ncd app\nnpm ci\nnpm run build\n```\n\n### OAuth configuration\n\nQueryWeaver supports Google and GitHub OAuth. Create OAuth credentials for each provider and paste the client IDs/secrets into your `.env` file.\n\n- Google: set authorized origin and callback `http://localhost:5000/login/google/authorized`\n- GitHub: set homepage and callback `http://localhost:5000/login/github/authorized`\n\n#### Environment-specific OAuth settings\n\nFor production/staging deployments, set `APP_ENV=production` or `APP_ENV=staging` in your environment to enable secure session cookies (HTTPS-only). This prevents OAuth CSRF state mismatch errors.\n\n```bash\n# For production/staging (enables HTTPS-only session cookies)\nAPP_ENV=production\n\n# For development (allows HTTP session cookies)\nAPP_ENV=development\n```\n\n**Important**: If you're getting \"mismatching_state: CSRF Warning!\" errors on staging/production, ensure `APP_ENV` is set to `production` or `staging` to enable secure session handling.\n\n### AI/LLM configuration\n\nQueryWeaver uses AI models for Text2SQL conversion and supports both Azure OpenAI and OpenAI directly.\n\n#### Default: Azure OpenAI\n\nBy default, QueryWeaver is configured to use Azure OpenAI. You need to set all three Azure credentials:\n\n```bash\nAZURE_API_KEY=your_azure_api_key\nAZURE_API_BASE=https://your-resource.openai.azure.com/\nAZURE_API_VERSION=2024-12-01-preview\n```\n\n#### Alternative: OpenAI directly\n\nTo use OpenAI directly instead of Azure, simply set the `OPENAI_API_KEY` environment variable:\n\n```bash\nOPENAI_API_KEY=your_openai_api_key\n```\n\nWhen `OPENAI_API_KEY` is provided, QueryWeaver automatically switches to use OpenAI's models:\n- Embedding model: `openai/text-embedding-ada-002`\n- Completion model: `openai/gpt-4.1`\n\nThis configuration is handled automatically in `api/config.py` - you only need to provide the appropriate API key.\n\n#### Docker examples with AI configuration\n\nUsing Azure OpenAI:\n```bash\ndocker run -p 5000:5000 -it \\\n  -e FASTAPI_SECRET_KEY=your_secret_key \\\n  -e AZURE_API_KEY=your_azure_api_key \\\n  -e AZURE_API_BASE=https://your-resource.openai.azure.com/ \\\n  -e AZURE_API_VERSION=2024-12-01-preview \\\n  falkordb/queryweaver\n```\n\nUsing OpenAI directly:\n```bash\ndocker run -p 5000:5000 -it \\\n  -e FASTAPI_SECRET_KEY=your_secret_key \\\n  -e OPENAI_API_KEY=your_openai_api_key \\\n  falkordb/queryweaver\n```\n\n## Testing\n\n\u003e Quick note: many tests require FalkorDB to be available. Use the included helper to run a test DB in Docker if needed.\n\n### Prerequisites\n\n- Install dev dependencies: `pipenv sync --dev`\n- Start FalkorDB (see `make docker-falkordb`)\n- Install Playwright browsers: `pipenv run playwright install`\n\n### Quick commands\n\nRecommended: prepare the development/test environment using the Make helper (installs dependencies and Playwright browsers):\n\n```bash\n# Prepare development/test environment (installs deps and Playwright browsers)\nmake setup-dev\n```\n\nAlternatively, you can run the E2E-specific setup script and then run tests manually:\n\n```bash\n# Prepare E2E test environment (installs browsers and other setup)\n./setup_e2e_tests.sh\n\n# Run all tests\nmake test\n\n# Run unit tests only (faster)\nmake test-unit\n\n# Run E2E tests (headless)\nmake test-e2e\n\n# Run E2E tests with a visible browser for debugging\nmake test-e2e-headed\n```\n\n### Test types\n\n- Unit tests: focus on individual modules and utilities. Run with `make test-unit` or `pipenv run pytest tests/ -k \"not e2e\"`.\n- End-to-end (E2E) tests: run via Playwright and exercise UI flows, OAuth, file uploads, schema processing, chat queries, and API endpoints. Use `make test-e2e`.\n\nSee `tests/e2e/README.md` for full E2E test instructions.\n\n### CI/CD\n\nGitHub Actions run unit and E2E tests on pushes and pull requests. Failures capture screenshots and artifacts for debugging.\n\n## Troubleshooting\n\n- FalkorDB connection issues: start the DB helper `make docker-falkordb` or check network/host settings.\n- Playwright/browser failures: install browsers with `pipenv run playwright install` and ensure system deps are present.\n- Missing environment variables: copy `.env.example` and fill required values.\n- **OAuth \"mismatching_state: CSRF Warning!\" errors**: Set `APP_ENV=production` (or `staging`) in your environment for HTTPS deployments, or `APP_ENV=development` for HTTP development environments. This ensures session cookies are configured correctly for your deployment type.\n\n## Project layout (high level)\n\n- `api/` – FastAPI backend\n- `app/` – React + Vite frontend\n- `tests/` – unit and E2E tests\n\n\n## License\n\nLicensed under the GNU Affero General Public License (AGPL). See [LICENSE](LICENSE.txt).\n\nCopyright FalkorDB Ltd. 2025\n\n","funding_links":[],"categories":["📦 Libraries"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFalkorDB%2FQueryWeaver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FFalkorDB%2FQueryWeaver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFalkorDB%2FQueryWeaver/lists"}