Scaffold Python package: hatchling build, src layout, CI

- Add pyproject.toml with hatchling backend, MIT license, Python 3.9+ support
- Set up src/textql/ package layout with version, client stub, exception hierarchy
- TextQL client reads TEXTQL_API_KEY / TEXTQL_BASE_URL from env; resource clients are deferred
- Add pytest tests for client construction and configuration
- Add GitHub Actions CI: ruff lint+format, pyright strict on src, pytest matrix Py 3.9-3.13
- Replace README placeholder with install/quickstart and status notice

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jlsajfj

.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Create venv
+        run: python -m venv .venv
+      - name: Install
+        run: |
+          .venv/bin/pip install --upgrade pip
+          .venv/bin/pip install -e ".[dev]"
+      - name: Ruff
+        run: .venv/bin/ruff check .
+      - name: Ruff format check
+        run: .venv/bin/ruff format --check .
+      - name: Pyright
+        run: .venv/bin/pyright
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Pytest
+        run: pytest

CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to the `textql` Python SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial repository scaffolding: `pyproject.toml`, `src/textql/` package layout, exception hierarchy, sync client stub.
+- CI workflow: ruff lint + format check, pyright strict, pytest on Python 3.9–3.13.

README.md

@@ -1,2 +1,69 @@
-# textql-python
-Official Python SDK for the TextQL Platform API
+# TextQL Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/textql.svg)](https://pypi.org/project/textql/)
+[![Python versions](https://img.shields.io/pypi/pyversions/textql.svg)](https://pypi.org/project/textql/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Official Python SDK for the [TextQL Platform API](https://docs.textql.com).
+
+> **Status:** v0.1.0 is a scaffolding release. Resource clients (`chat`, `playbooks`, `sandbox`, `connectors`) are stubs and not yet functional.
+
+## Installation
+
+```bash
+pip install textql
+```
+
+Requires Python 3.9+.
+
+## Quickstart
+
+```python
+from textql import TextQL
+
+client = TextQL(api_key="tql_...")  # or set TEXTQL_API_KEY in the environment
+```
+
+Once resource clients land, the surface will look like:
+
+```python
+# Simple chat
+response = client.chat.create(question="What was total revenue last quarter?")
+
+# Streaming
+for event in client.chat.stream(question="..."):
+    print(event.text, end="", flush=True)
+
+# File upload
+response = client.chat.create(
+    question="Analyze this",
+    files=[{"path": "./sales.csv"}],
+)
+```
+
+## Configuration
+
+| Option | Env var | Default |
+|---|---|---|
+| `api_key` | `TEXTQL_API_KEY` | — (required) |
+| `base_url` | `TEXTQL_BASE_URL` | `https://api.textql.com` |
+| `timeout` | — | `60.0` seconds |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check . && ruff format --check .
+pyright
+pytest
+```
+
+## Links
+
+- [API documentation](https://docs.textql.com)
+- [Changelog](CHANGELOG.md)
+- [Issues](https://github.com/TextQLLabs/textql-python/issues)
+
+## License
+
+[MIT](LICENSE)

pyproject.toml

@@ -0,0 +1,84 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "textql"
+description = "Official Python SDK for the TextQL Platform API"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.9"
+authors = [{ name = "TextQL", email = "support@textql.com" }]
+keywords = ["textql", "sdk", "api", "analytics", "ana"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dynamic = ["version"]
+dependencies = [
+    "httpx >=0.27,<1",
+    "typing_extensions >=4.7; python_version < '3.11'",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest >=8",
+    "pytest-asyncio >=0.23",
+    "ruff >=0.6",
+    "pyright >=1.1.380",
+    "respx >=0.21",
+]
+
+[project.urls]
+Homepage = "https://textql.com"
+Documentation = "https://docs.textql.com"
+Repository = "https://github.com/TextQLLabs/textql-python"
+Issues = "https://github.com/TextQLLabs/textql-python/issues"
+Changelog = "https://github.com/TextQLLabs/textql-python/blob/main/CHANGELOG.md"
+
+[tool.hatch.version]
+path = "src/textql/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/textql"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # bugbear
+    "UP",  # pyupgrade
+    "RUF", # ruff-specific
+]
+
+[tool.pyright]
+include = ["src", "tests"]
+pythonVersion = "3.9"
+typeCheckingMode = "strict"
+venvPath = "."
+venv = ".venv"
+
+[[tool.pyright.executionEnvironments]]
+root = "tests"
+reportUnknownMemberType = "none"
+reportUnknownParameterType = "none"
+reportUnknownVariableType = "none"
+reportMissingParameterType = "none"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

src/textql/__init__.py

@@ -0,0 +1,25 @@
+from ._client import TextQL
+from ._exceptions import (
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    TextQLError,
+)
+from ._version import __version__
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "APITimeoutError",
+    "AuthenticationError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "TextQL",
+    "TextQLError",
+    "__version__",
+]

src/textql/_client.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from ._version import __version__
+
+DEFAULT_BASE_URL = "https://api.textql.com"
+DEFAULT_TIMEOUT = 60.0
+
+
+class TextQL:
+    """Synchronous client for the TextQL Platform API.
+
+    Resource clients (`chat`, `playbooks`, `sandbox`, `connectors`) are stubs
+    in v0.1.0 — they will be filled in as the v2 SDK takes shape.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        key = api_key or os.environ.get("TEXTQL_API_KEY")
+        if not key:
+            raise ValueError(
+                "No API key provided. Pass api_key=... or set TEXTQL_API_KEY in the environment."
+            )
+
+        self.api_key = key
+        resolved_base = base_url or os.environ.get("TEXTQL_BASE_URL") or DEFAULT_BASE_URL
+        self.base_url = resolved_base.rstrip("/")
+        self._http = http_client or httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers=self._default_headers(),
+        )
+
+    def _default_headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "User-Agent": f"textql-python/{__version__}",
+            "Accept": "application/json",
+        }
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> TextQL:
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()

src/textql/_exceptions.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+
+class TextQLError(Exception):
+    """Base class for all TextQL SDK errors."""
+
+
+class APIError(TextQLError):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.request_id = request_id
+
+
+class AuthenticationError(APIError):
+    pass
+
+
+class PermissionDeniedError(APIError):
+    pass
+
+
+class NotFoundError(APIError):
+    pass
+
+
+class RateLimitError(APIError):
+    pass
+
+
+class APIConnectionError(TextQLError):
+    pass
+
+
+class APITimeoutError(APIConnectionError):
+    pass

src/textql/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

tests/test_client.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import pytest
+
+from textql import TextQL, __version__
+
+
+def test_version_is_set() -> None:
+    assert __version__
+
+
+def test_client_requires_api_key(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("TEXTQL_API_KEY", raising=False)
+    with pytest.raises(ValueError, match="No API key"):
+        TextQL()
+
+
+def test_client_reads_api_key_from_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("TEXTQL_API_KEY", "tql_test_123")
+    client = TextQL()
+    assert client.api_key == "tql_test_123"
+
+
+def test_client_explicit_api_key_overrides_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("TEXTQL_API_KEY", "from_env")
+    client = TextQL(api_key="explicit")
+    assert client.api_key == "explicit"
+
+
+def test_client_strips_trailing_slash_from_base_url() -> None:
+    client = TextQL(api_key="tql_x", base_url="https://example.com/")
+    assert client.base_url == "https://example.com"
+
+
+def test_client_context_manager() -> None:
+    with TextQL(api_key="tql_x") as client:
+        assert client.api_key == "tql_x"