aaizaql 0.1.0__tar.gz

aaizaql-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,103 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  lint:
+    name: Lint & Format
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install linting tools
+        run: pip install ruff black mypy
+
+      - name: Ruff auto-fix
+        run: ruff check src/ tests/ --fix --unsafe-fixes
+
+      - name: Black auto-format
+        run: black src/ tests/
+
+      - name: Commit fixes if needed
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git diff --quiet && echo "No changes" || (git add -A && git commit -m "style: auto-fix ruff and black formatting")
+
+      - name: Push fixes
+        run: git push
+
+      - name: Ruff final check (must pass clean)
+        run: ruff check src/ tests/
+
+  test:
+    name: Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package + dev dependencies
+        run: |
+          pip install -e ".[duckdb,mysql,snowflake]"
+          pip install pytest pytest-cov pytest-asyncio
+
+      - name: Run tests
+        run: pytest tests/ --cov=src/aaizaql --cov-report=term-missing
+
+      - name: Upload coverage report
+        uses: actions/upload-artifact@v4
+        if: matrix.python-version == '3.11'
+        with:
+          name: coverage-report
+          path: .coverage
+
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Build wheel + sdist
+        run: |
+          pip install hatchling build
+          python -m build
+
+      - name: Check distribution metadata
+        run: |
+          pip install twine
+          twine check dist/*
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

aaizaql-0.1.0/.gitignore

@@ -0,0 +1,94 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Secrets / credentials
+.env.local
+.env.production
+secrets.toml
+
+# Testing
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+pytestdebug.log
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Jupyter
+.ipynb_checkpoints
+*.ipynb_checkpoints
+
+# Vector store data (local dev)
+.nlsql_chroma/
+.chroma/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Distribution
+*.tar.gz
+*.whl
+
+# Docs build
+docs/_build/
+site/
+
+# Logs
+*.log
+audit_*.jsonl
+
+*.db
+.aqlix_chroma/
+
+aqlix.zip
+*.zip
+
+.pypirc
+*.pem
+*.key
+.pypirc

aaizaql-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,39 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-json
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: ["--maxkb=500"]
+      - id: debug-statements
+      - id: no-commit-to-branch
+        args: ["--branch", "main"]
+
+  - repo: https://github.com/psf/black
+    rev: 24.4.2
+    hooks:
+      - id: black
+        language_version: python3.11
+
+  - repo: https://github.com/PyCQA/flake8
+    rev: 7.0.0
+    hooks:
+      - id: flake8
+        args:
+          - "--max-line-length=100"
+          - "--extend-ignore=E203,W503"
+          - "--exclude=.git,__pycache__,.venv,build,dist"
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.9.0
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - pydantic>=2.0
+          - pydantic-settings>=2.0
+        args: ["--ignore-missing-imports"]

aaizaql-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,250 @@
+# Contributing to AAIZAQL
+
+Contributions are welcome — bug fixes, new connectors, LLM providers, docs, and tests all help.
+This guide covers everything you need to go from zero to a merged pull request.
+
+---
+
+## Table of contents
+
+- [Getting started](#getting-started)
+- [Project structure](#project-structure)
+- [Running tests](#running-tests)
+- [Code style](#code-style)
+- [Types of contributions](#types-of-contributions)
+- [Pull request process](#pull-request-process)
+- [Commit message format](#commit-message-format)
+- [Reporting bugs](#reporting-bugs)
+
+---
+
+## Getting started
+
+**Requirements:** Python 3.11+, Git.
+
+```bash
+git clone https://github.com/ibrahimkhalilCorp/AAIZAQL
+cd AAIZAQL
+pip install -e ".[dev]"
+pre-commit install
+```
+
+That installs the library in editable mode with all dev dependencies (pytest, black, ruff, mypy)
+and registers the pre-commit hooks so formatting runs automatically before every commit.
+
+Verify the setup works:
+
+```bash
+pytest tests/unit/          # fast, no API key needed
+```
+
+---
+
+## Project structure
+
+```
+src/AAIZAQL/
+├── core/          # QueryEngine, Settings, exceptions — the public API
+├── nlp/           # SQLGenerator, SelfCorrector, prompts
+├── memory/        # ContextManager, VectorStoreAdapter
+├── security/      # SQLValidator, AuditLogger
+├── connectors/    # One file per database (sqlite, postgres, mysql, …)
+├── llm/           # One file per LLM provider (claude, openai, groq, ollama)
+├── federation/    # FederationCoordinator, QueryPlanner (Phase 3)
+├── schema/        # SchemaIngester, SemanticLayer
+├── visualization/ # ResultRenderer, NLSummarizer
+└── cli.py         # `AAIZAQL` command-line entry point
+tests/
+├── unit/          # Pure unit tests — no DB, no API key, always fast
+├── integration/   # Tests against a real SQLite database
+└── conftest.py    # Shared fixtures (sqlite_db, mock_llm, vector_store, …)
+```
+
+The most important rule: **every layer has one job.**
+The NLP layer produces SQL. The security layer validates it. The execution layer runs it.
+Never mix concerns across layers.
+
+---
+
+## Running tests
+
+```bash
+# Unit tests only (fast, no external deps)
+pytest tests/unit/
+
+# Full test suite (requires chromadb and sentence-transformers)
+pytest tests/
+
+# With coverage report
+pytest tests/ --cov=src/AAIZAQL --cov-report=term-missing
+
+# Run a specific file
+pytest tests/unit/test_validator.py -v
+```
+
+Tests marked `@pytest.mark.requires_api_key` are automatically skipped when no
+`ANTHROPIC_API_KEY` or `OPENAI_API_KEY` environment variable is set. To run them locally:
+
+```bash
+export AAIZAQL_GROQ_API_KEY="gsk_..."
+pytest tests/ -m requires_api_key
+```
+
+---
+
+## Code style
+
+The CI pipeline enforces all of these automatically. Running `pre-commit install` means
+they also run locally before every commit.
+
+| Tool | What it does | Config |
+|---|---|---|
+| `black` | Formats code | `pyproject.toml` → `[tool.black]` |
+| `ruff` | Lints and auto-fixes | `pyproject.toml` → `[tool.ruff]` |
+| `mypy` | Type-checks (non-strict) | `pyproject.toml` → `[tool.mypy]` |
+
+Line length is **100 characters**. Use type hints everywhere. Avoid bare `Exception` —
+raise the specific exception from `AAIZAQL.core.exceptions` that matches the failure.
+
+To run checks manually:
+
+```bash
+black src/ tests/
+ruff check src/ tests/ --fix
+mypy src/
+```
+
+---
+
+## Types of contributions
+
+### Adding a new database connector
+
+1. Create `src/AAIZAQL/connectors/<name>.py` — subclass `DatabaseConnector` and implement
+   `connect()`, `execute()`, `get_schema()`, and `close()`. Follow the pattern in
+   `connectors/sqlite.py` or `connectors/postgres.py`.
+
+2. Add a lazy-import block in `src/AAIZAQL/connectors/__init__.py`:
+
+   ```python
+   try:
+       from AAIZAQL.connectors.bigquery import BigQueryConnector
+       REGISTRY["bigquery"] = BigQueryConnector
+   except ImportError:
+       pass
+   ```
+
+3. Add the driver to `pyproject.toml` as an optional dependency:
+
+   ```toml
+   [project.optional-dependencies]
+   bigquery = ["google-cloud-bigquery>=3.0"]
+   ```
+
+4. Write tests in `tests/test_connectors.py` following the existing pattern.
+
+### Adding a new LLM provider
+
+1. Create `src/AAIZAQL/llm/<name>_provider.py` — subclass `LLMProvider` and implement
+   `complete()`. Follow the pattern in `llm/groq_provider.py`.
+
+2. Register it in `src/AAIZAQL/llm/__init__.py`.
+
+3. Add the SDK to `pyproject.toml` as an optional dependency.
+
+4. Update the `Supported LLM Providers` table in `README.md`.
+
+### Fixing a bug
+
+- Open an issue first if the fix is non-trivial, so we can agree on the approach.
+- Include a failing test that reproduces the bug in your PR.
+- The fix and the test should be in the same commit.
+
+### Improving documentation
+
+- Docs changes (README, docstrings, examples) are always welcome without an issue first.
+- Example notebooks live in `examples/` — follow the naming convention
+  `NN_short_description.py` (e.g. `04_snowflake_quickstart.py`).
+
+---
+
+## Pull request process
+
+1. **Fork** the repo and create a branch from `main`:
+
+   ```bash
+   git checkout -b feat/bigquery-connector
+   ```
+
+2. **Write tests** for your change. PRs without tests for new behaviour will be asked
+   to add them before merging.
+
+3. **Make sure CI passes** locally before pushing:
+
+   ```bash
+   pytest tests/unit/
+   ruff check src/ tests/
+   black --check src/ tests/
+   ```
+
+4. **Open a PR** against `main`. Fill in the PR template:
+   - What does this change?
+   - Why is it needed?
+   - How was it tested?
+
+5. **One approval** from a maintainer is required to merge. Small fixes (typos, docs)
+   can be merged by a maintainer directly.
+
+6. Squash-merge is preferred for feature branches to keep the `main` history clean.
+
+---
+
+## Commit message format
+
+Use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>: <short summary in sentence case>
+
+<optional body explaining why, not what>
+```
+
+Common types:
+
+| Type | When to use |
+|---|---|
+| `feat` | New feature or connector |
+| `fix` | Bug fix |
+| `test` | Adding or fixing tests |
+| `docs` | Documentation only |
+| `style` | Formatting, no logic change |
+| `refactor` | Code change with no behaviour change |
+| `chore` | Build scripts, CI, dependencies |
+
+Examples:
+
+```
+feat: add BigQuery connector
+fix: handle empty result set in NLSummarizer
+docs: add Snowflake quickstart example
+test: add unit tests for MySQLConnector DSN parser
+```
+
+---
+
+## Reporting bugs
+
+Open a [GitHub issue](https://github.com/ibrahimkhalilCorp/AAIZAQL/issues) and include:
+
+- AAIZAQL version (`pip show AAIZAQL`)
+- Python version (`python --version`)
+- Database and LLM provider being used
+- The question you asked and the SQL that was generated (if any)
+- The full error traceback
+
+For security vulnerabilities, do **not** open a public issue.
+Email the maintainer directly (see the `authors` field in `pyproject.toml`).
+
+---
+
+MIT License — by contributing you agree your work will be released under the same license.

aaizaql-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ibrahim Khalil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.