{"id":50982153,"url":"https://github.com/aladagemre/aisql","last_synced_at":"2026-06-19T15:33:21.966Z","repository":{"id":365725097,"uuid":"952832387","full_name":"aladagemre/aisql","owner":"aladagemre","description":"A powerful AI-powered SQL and MongoDB query generator that converts natural language questions into optimized database queries.","archived":false,"fork":false,"pushed_at":"2026-01-26T02:13:38.000Z","size":192,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-18T16:28:47.365Z","etag":null,"topics":["ai","mongodb","sql"],"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/aladagemre.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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-03-22T01:03:37.000Z","updated_at":"2026-01-29T23:25:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aladagemre/aisql","commit_stats":null,"previous_names":["aladagemre/aisql"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/aladagemre/aisql","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aladagemre%2Faisql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aladagemre%2Faisql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aladagemre%2Faisql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aladagemre%2Faisql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aladagemre","download_url":"https://codeload.github.com/aladagemre/aisql/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aladagemre%2Faisql/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34538220,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-19T02:00:06.005Z","response_time":61,"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":["ai","mongodb","sql"],"created_at":"2026-06-19T15:33:21.131Z","updated_at":"2026-06-19T15:33:21.951Z","avatar_url":"https://github.com/aladagemre.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI SQL Generator\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\nA powerful AI-powered SQL and MongoDB query generator that converts natural language questions into optimized database queries.\n\n## 🎬 Demo\n\n```\n    ╔═══════════════════════════════════════════════════════════╗\n    ║                                                           ║\n    ║     █████╗ ██╗███████╗ ██████╗ ██╗                        ║\n    ║    ██╔══██╗██║██╔════╝██╔═══██╗██║                        ║\n    ║    ███████║██║███████╗██║   ██║██║                        ║\n    ║    ██╔══██║██║╚════██║██║▄▄ ██║██║                        ║\n    ║    ██║  ██║██║███████║╚██████╔╝███████╗                   ║\n    ║    ╚═╝  ╚═╝╚═╝╚══════╝ ╚══▀▀═╝ ╚══════╝                   ║\n    ║                                                           ║\n    ║    Natural Language to SQL Generator                      ║\n    ╚═══════════════════════════════════════════════════════════╝\n\nUsing OPENAI_API_KEY from environment: ************\n\n\u003e Show me all customers who ordered in the last 30 days\n\nGenerating SQL...\n\n============================================================\nSQL Query:\n------------------------------------------------------------\nSELECT DISTINCT c.id, c.name, c.email\nFROM customers c\nJOIN orders o ON c.id = o.customer_id\nWHERE o.order_date \u003e= CURRENT_DATE - INTERVAL '30 days';\n------------------------------------------------------------\n\nExplanation: This query retrieves unique customer records (id, name, email)\nfor customers who have placed at least one order in the last 30 days.\nValid: Yes\n============================================================\n\n\u003e What are the top 5 products by total sales?\n\nGenerating SQL...\n\n============================================================\nSQL Query:\n------------------------------------------------------------\nSELECT p.id, p.name, SUM(oi.quantity * oi.unit_price) AS total_sales\nFROM products p\nJOIN order_items oi ON p.id = oi.product_id\nGROUP BY p.id, p.name\nORDER BY total_sales DESC\nLIMIT 5;\n------------------------------------------------------------\n\nExplanation: This query calculates total sales for each product and returns\nthe top 5 products ranked by their total sales amount.\nValid: Yes\n============================================================\n\n\u003e /quit\nGoodbye!\n```\n\nRun the animated demo yourself:\n```bash\nmake demo\n```\n\n## 🚀 Features\n\n- Natural language to SQL query conversion\n- Natural language to MongoDB query conversion\n- Detailed query explanations\n- Query validation against user intent\n- Interactive CLI with custom schema support\n- RESTful API interface\n\n## 📋 Requirements\n\n- Python 3.10+\n- [uv](https://github.com/astral-sh/uv) package manager\n- OpenAI API key\n\n## 🛠 Installation\n\n### Install from PyPI\n\n```bash\npip install aisql\n\n# Development extras (formatting, linting, tests)\npip install \"aisql[dev]\"\n```\n\n### Install from source\n\n1. Clone the repository\n\n    ```bash\n    git clone https://github.com/aladagemre/aisql.git\n    cd aisql\n    ```\n\n2. Install uv (if not already installed)\n\n    ```bash\n    # macOS/Linux\n    curl -LsSf https://astral.sh/uv/install.sh | sh\n\n    # Or with Homebrew\n    brew install uv\n\n    # Or with pip\n    pip install uv\n    ```\n\n3. Install dependencies\n\n    ```bash\n    uv sync\n    ```\n\n4. Set up your OpenAI API key\n\nOption A: Set environment variable (recommended)\n```bash\nexport OPENAI_API_KEY=\"your-api-key-here\"\n```\n\nOption B: Create a `.env` file\n```bash\ncp .env.example .env\n# Edit .env and add your OpenAI API key\n```\n\nOption C: Enter interactively when running the CLI\n\nOptional: Use deterministic mocks without calling the OpenAI API\n```bash\nexport AISQL_USE_MOCK=true\n```\n\n## 🖥 Running the CLI\n\nThe interactive CLI is the easiest way to use AISQL:\n\n```bash\nmake cli\n```\n\nOr directly with Python:\n```bash\nuv run python -m aisql.cli\n```\n\nOnce installed, you can also run:\n```bash\naisql-cli\n```\n\nOnce installed, you can also run:\n```bash\naisql-cli\n```\n\n### CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `/help` | Show available commands |\n| `/schema` | View current database schema |\n| `/set schema` | Define a custom schema (multi-line input) |\n| `/set key` | Change OpenAI API key |\n| `/clear` | Clear the screen |\n| `/quit` | Exit the application |\n\n### Example Session\n\n```\n\u003e /schema\n\nCurrent Schema:\n----------------------------------------\nTable: customers\n- id (int, primary key)\n- name (varchar)\n- email (varchar)\n- created_at (timestamp)\n\nTable: orders\n- id (int, primary key)\n- customer_id (int, foreign key -\u003e customers.id)\n- order_date (date)\n- total (decimal)\n- status (varchar)\n----------------------------------------\n\n\u003e Find customers who spent more than $1000 but haven't ordered in 90 days\n\n============================================================\nSQL Query:\n------------------------------------------------------------\nSELECT c.id, c.name, c.email, SUM(o.total) AS total_spent,\n       MAX(o.order_date) AS last_order_date\nFROM customers c\nJOIN orders o ON c.id = o.customer_id\nGROUP BY c.id, c.name, c.email\nHAVING SUM(o.total) \u003e 1000\n   AND MAX(o.order_date) \u003c CURRENT_DATE - INTERVAL '90 days';\n------------------------------------------------------------\n\nExplanation: This query identifies high-value customers (\u003e$1000 total spend)\nwho have become inactive (no orders in the last 90 days).\nValid: Yes\n============================================================\n```\n\n## 🎬 Running the Demo\n\nWatch an animated demonstration of the CLI:\n\n```bash\nmake demo\n```\n\nOr directly:\n```bash\nuv run python demo_cast.py\n```\n\n## 🌐 Running the REST API\n\nStart the API server:\n\n```bash\nmake run\n```\n\nOr directly:\n```bash\nuv run uvicorn aisql.main:app --reload\n```\n\nOnce installed, you can also run:\n```bash\naisql-api\n```\n\nOnce installed, you can also run:\n```bash\naisql-api\n```\n\nThe API will be available at `http://localhost:8000`\n\n### API Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/` | API info |\n| GET | `/demo` | Interactive web demo |\n| GET | `/docs` | Swagger documentation |\n| POST | `/generate-postgresql` | Generate SQL query |\n| POST | `/generate-mongodb` | Generate MongoDB query |\n\n### API Example\n\n```bash\ncurl -X POST \"http://localhost:8000/generate-postgresql\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\"question\": \"Show me all customers who ordered in the last 30 days\"}'\n```\n\nResponse:\n```json\n{\n    \"query\": \"SELECT DISTINCT c.id, c.name, c.email FROM customers c JOIN orders o ON c.id = o.customer_id WHERE o.order_date \u003e= CURRENT_DATE - INTERVAL '30 days';\",\n    \"explanation\": \"This query retrieves unique customers who have placed orders in the last 30 days.\",\n    \"is_valid\": true,\n    \"error\": null\n}\n```\n\n## 🧱 SDK Usage\n\nImport the generators directly in your Python project:\n\n```python\nfrom aisql.lib import SQLGenerator\nfrom aisql.schemas import POSTGRESQL_SCHEMA\n\ngenerator = SQLGenerator(schema=POSTGRESQL_SCHEMA)\nresult = generator.generate(\"Show me all customers who ordered in the last 30 days\")\nprint(result.query)\nprint(result.explanation)\n```\n\nSet `OPENAI_API_KEY` before instantiating the generators, or export `AISQL_USE_MOCK=true` to run with the deterministic offline mocks used in the test suite.\n\n## 🧪 Testing\n\nRun the test suite:\n```bash\nmake test\n```\n\nOr directly:\n```bash\nuv run pytest -v\n```\n\nTests use deterministic mock query generators so they can run without an\n`OPENAI_API_KEY`. Integration testing with the real OpenAI models still works\nby running the application normally.\n\n## 🛠 Development\n\nFormat code:\n```bash\nmake format\n```\n\nRun linter:\n```bash\nmake lint\n```\n\n## 📁 Project Structure\n\n```\naisql/\n├── aisql/\n│   ├── __init__.py\n│   ├── cli.py           # Interactive CLI\n│   ├── lib.py           # Query generation logic\n│   ├── main.py          # FastAPI application\n│   ├── models.py        # Pydantic models\n│   ├── schemas/         # Database schema definitions\n│   └── templates/       # HTML templates\n├── tests/               # Test suite\n├── demo_cast.py         # ASCII cinema demo\n├── Makefile             # Build commands\n└── pyproject.toml       # Project configuration\n```\n\n## 🤝 Contributing\n\nContributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🔒 Security\n\nFor security concerns, please see our [Security Policy](SECURITY.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faladagemre%2Faisql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faladagemre%2Faisql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faladagemre%2Faisql/lists"}