sageql 0.2.1__tar.gz

sageql-0.2.1/.env.example

@@ -0,0 +1,14 @@
+# Copy this file to .env and fill in values you want to reuse.
+# Leave a field blank to enter it interactively when the chat starts.
+# Authentication is the method name only; do not put a database password here.
+DB_SERVER_HOST=
+DB_NAME=
+DB_AUTHENTICATION=
+DB_ODBC_DRIVER=
+# Path to the structured table/column catalog supplied by the package user.
+SCHEMA_CATALOG_PATH=
+
+# Keep your real API key only in the ignored .env file or an environment variable.
+LLM_API_KEY=
+LLM_BASE_URL=https://api.avalai.ir/v1
+LLM_MODEL=gpt-5-nano

sageql-0.2.1/.github/workflows/compatibility.yml

@@ -0,0 +1,122 @@
+name: Offline compatibility and package integrity
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  package:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: '3.12'
+          cache: pip
+      - run: python -m pip --isolated install --index-url https://pypi.org/simple 'build>=1,<2'
+      - run: python -m build --outdir dist/packages
+        env:
+          SOURCE_DATE_EPOCH: '1735689600'
+      - run: >-
+          python tools/release_check.py archives --source .
+          --wheel dist/packages/sageql-*-py3-none-any.whl
+          --sdist dist/packages/sageql-*.tar.gz
+          --output dist/inventory.json
+      - uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6
+        with:
+          name: reviewed-packages
+          path: |
+            dist/packages/*
+            dist/inventory.json
+
+  runtime:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - {os: ubuntu-latest, python: '3.10', bounds: lower}
+          - {os: windows-latest, python: '3.10', bounds: lower}
+          - {os: ubuntu-latest, python: '3.11', bounds: current}
+          - {os: windows-latest, python: '3.12', bounds: extras}
+          - {os: ubuntu-latest, python: '3.13', bounds: current}
+          - {os: windows-latest, python: '3.13', bounds: current}
+          - {os: ubuntu-latest, python: '3.14', bounds: current}
+          - {os: ubuntu-latest, python: '3.15', bounds: current}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - name: Create a clean runtime environment
+        run: |
+          python -m venv dist/runtime
+          if [ "$RUNNER_OS" = "Windows" ]; then
+            echo "RUNTIME_PYTHON=$PWD/dist/runtime/Scripts/python.exe" >> "$GITHUB_ENV"
+          else
+            echo "RUNTIME_PYTHON=$PWD/dist/runtime/bin/python" >> "$GITHUB_ENV"
+          fi
+      - name: Install core with declared lower bounds
+        if: matrix.bounds == 'lower'
+        run: '"$RUNTIME_PYTHON" -m pip --isolated install --index-url https://pypi.org/simple . sqlglot==26.0.0 python-dotenv==1.2.0'
+      - name: Install independently resolved current core
+        if: matrix.bounds != 'lower'
+        run: '"$RUNTIME_PYTHON" -m pip --isolated install --index-url https://pypi.org/simple .'
+      - name: Installed core imports and examples (before testing extras)
+        run: '"$RUNTIME_PYTHON" -I tools/release_check.py smoke --source . --core-only --output dist/core-smoke.json'
+      - name: Install current optional extras
+        if: matrix.bounds == 'extras'
+        run: '"$RUNTIME_PYTHON" -m pip --isolated install --index-url https://pypi.org/simple ".[openai,odbc,dev]"'
+      - name: Real optional imports and client construction without network
+        if: matrix.bounds == 'extras'
+        run: '"$RUNTIME_PYTHON" -I tools/release_check.py smoke --source . --extras --output dist/extras-smoke.json'
+      - name: Install minimum test tooling
+        if: matrix.bounds == 'lower'
+        run: '"$RUNTIME_PYTHON" -m pip --isolated install --index-url https://pypi.org/simple pytest==8.0.0'
+      - name: Install current test tooling
+        if: matrix.bounds == 'current'
+        run: '"$RUNTIME_PYTHON" -m pip --isolated install --index-url https://pypi.org/simple "pytest>=8,<10"'
+      - name: SQLite-first tests and every offline evaluation
+        run: '"$RUNTIME_PYTHON" tools/release_check.py offline --source . --output dist/gates/results.json'
+      - uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6
+        if: always()
+        with:
+          name: evidence-${{ matrix.os }}-${{ matrix.python }}-${{ matrix.bounds }}
+          path: |
+            dist/gates/
+            dist/*smoke.json
+          retention-days: 14
+
+  source-install:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: '3.12'
+      - run: python -m pip --isolated install --index-url https://pypi.org/simple 'build>=1,<2'
+      - run: python -m build --outdir dist/packages
+      - run: python -m venv dist/from-sdist
+      - run: dist/from-sdist/bin/python -m pip --isolated install --index-url https://pypi.org/simple dist/packages/sageql-*.tar.gz
+      - run: dist/from-sdist/bin/python -I tools/release_check.py smoke --source . --core-only --output dist/sdist-smoke.json
+      - run: python -m venv dist/editable
+      - run: dist/editable/bin/python -m pip --isolated install --index-url https://pypi.org/simple -e .
+      - run: dist/editable/bin/python -I tools/release_check.py smoke --source . --core-only --editable --output dist/editable-smoke.json

sageql-0.2.1/.github/workflows/publish.yml

@@ -0,0 +1,56 @@
+name: Publish to PyPI
+
+# Runs when a version tag is pushed. PyPI trusts this workflow through OIDC
+# (trusted publishing), so no API token is stored in the repository.
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: '3.12'
+      - name: Tag matches the package version
+        run: |
+          version=$(sed -n 's/^version = "\(.*\)"/\1/p' pyproject.toml)
+          test "v$version" = "$GITHUB_REF_NAME" || { echo "Tag $GITHUB_REF_NAME does not match version $version"; exit 1; }
+      - run: python -m pip --isolated install --index-url https://pypi.org/simple 'build>=1,<2' 'twine>=7,<8'
+      - run: python -m build --outdir dist/packages
+        env:
+          SOURCE_DATE_EPOCH: '1735689600'
+      - run: >-
+          python tools/release_check.py archives --source .
+          --wheel dist/packages/sageql-*-py3-none-any.whl
+          --sdist dist/packages/sageql-*.tar.gz
+          --output dist/inventory.json
+      - run: python -m twine check --strict dist/packages/*
+      - uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6
+        with:
+          name: distributions
+          path: dist/packages/*
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/project/sageql/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6
+        with:
+          name: distributions
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

sageql-0.2.1/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+dist/
+*.egg-info/
+.env
+# Private Rahtal host: kept locally, never published.
+sageql_rahtal/
+docs/RAHTAL_MANUAL_TEST.md
+tests/test_rahtal_*.py
+tests/test_tsql_rahtal.py
+.claude/

sageql-0.2.1/AGENTS.md

@@ -0,0 +1,15 @@
+# SageQL agent entry point
+
+Read [agent-rules/Agent.md](agent-rules/Agent.md) before changing anything. It holds
+the product contract, the hard safety rules and the working workflow.
+
+Where things are:
+
+- Current state and ordered next steps: [docs/ROADMAP.md](docs/ROADMAP.md).
+- Rationale for the plan: [docs/IMPROVEMENT_RECOMMENDATIONS.md](docs/IMPROVEMENT_RECOMMENDATIONS.md).
+- Feature contracts: `docs/SDK*.md` (saved reports: [docs/SDK_SAVED_REPORTS.md](docs/SDK_SAVED_REPORTS.md)) (start with [docs/SDK.md](docs/SDK.md) and
+  [docs/SDK_AGENTS.md](docs/SDK_AGENTS.md)).
+- Tests: [docs/SQLITE_FIRST_TESTING.md](docs/SQLITE_FIRST_TESTING.md); evaluations:
+  [evaluations/README.md](evaluations/README.md).
+
+When reporting work, include a commit message based on the actual changes.

sageql-0.2.1/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+## 0.2.1 — 2026-10-30
+
+First release published to PyPI (`pip install sageql`). No SDK behavior changes.
+
+### Fixed
+- CI: frozen evaluation inputs are hashed with LF-normalized line endings
+  (`evaluations/frozen.py`), so the offline gate passes on any checkout; package
+  jobs no longer hard-code the `0.1.0` archive names.
+
+### Changed
+- README rewritten around the design, measured results and an offline
+  quickstart; the long feature description moved to `docs/CAPABILITIES.md`.
+- Package metadata: author, keywords, classifiers and project URLs. README links
+  are absolute so they work on PyPI.
+
+### Added
+- Tag-triggered PyPI release workflow using trusted publishing (no stored token).
+
+### Removed
+- The private Rahtal host (`sageql_rahtal/`), its dedicated tests and manual test
+  guide are no longer published or packaged. Tests that use its catalog skip
+  when it is absent.
+
+## 0.2.0 — 2026-10-30
+
+Cheaper, faster and more accurate report understanding, plus saved reports.
+
+### Added
+- **Saved reports**: save a finished report and re-run it with zero model calls,
+  fresh data and moving dates (`save_report`, `list_saved_reports`,
+  `run_saved_report`, `delete_saved_report`; in-memory and SQLite stores).
+  See `docs/SDK_SAVED_REPORTS.md`.
+- **Per-stage models and reasoning effort** on `OpenAIReportAgent`
+  (`stage_models`, `reasoning_effort`) and per-stage token usage events.
+- **`OpenAIReportAgent.recommended(config)`**: the measured cheap setup
+  (mini intent, compiled spec, no reviewer call, low reasoning effort).
+- **`compile_intent`**: a complete intent compiles locally, skipping the planner call.
+- **`review=False`**: accept candidates that pass every local check without a reviewer call.
+- **`intent_samples`**: optional parallel intent extractions with an agreement
+  vote; one failed sample no longer fails the turn (live accuracy not yet measured).
+- **Report interpretation**: each report lists the filters, conditions, sort and
+  row limit it applied (`provenance["interpretation"]`), shown on the web page.
+- **Rahtal test panel and guide**: 20 example questions with expected outcomes
+  and read-only SQL cross-checks (private guide).
+- **Live evaluation levels** (`smoke`, `standard`, `full`) with hard spending caps,
+  per-model pricing, and a halt on HTTP 429.
+
+### Changed
+- Rahtal and the reference web host use mini intent, compiled spec, no reviewer
+  call and low reasoning effort: 22/27 correct synthetic reports versus 6/27 for
+  nano everywhere, ~7 s and usually one model call per turn.
+- SDK defaults are unchanged for backward compatibility; use `recommended()`.
+
+### Fixed
+- Model output that filled controls marked "unspecified" with placeholder
+  values is cleaned instead of rejected.
+- A ranking with no chosen measure asks for it instead of sorting by a default metric.
+- Report interpretation never shows identities resolved from name lookups.
+
+### Removed
+- Historical phase reports, procedures and versioned evidence (kept in git history).
+
+### Known limits
+- Released without the manual Rahtal real-data check; live checks cover the
+  synthetic legacy cohort (21/21 turns correct).
+- Native SQL Server behavior unverified; local workspace token instead of user login.
+- No share-of-total, absence or per-group top-N operations; saved reports are personal.

sageql-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sina Qasempour
+
+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.