querri 1.0.2__tar.gz

querri-1.0.2/.github/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing to querri
+
+Thanks for your interest in contributing! This guide will help you get started.
+
+## Getting started
+
+1. Fork and clone the repository
+2. Install dependencies:
+   ```sh
+   pip install -e ".[dev]"
+   ```
+3. Run tests:
+   ```sh
+   pytest tests/ -v
+   ```
+4. Run linting and type checking:
+   ```sh
+   ruff check querri/ tests/
+   mypy querri/
+   ```
+
+## Project structure
+
+```
+querri/
+  resources/    API resource classes (Users, Projects, Dashboards, Sources, Data, etc.)
+  types/        Pydantic v2 models for API request/response types
+  _client.py    Querri / AsyncQuerri public entry points
+  _base_client.py  SyncHTTPClient / AsyncHTTPClient with auth, retries, error mapping
+  _user_client.py  UserQuerri / AsyncUserQuerri for embed session auth
+  _config.py    Configuration resolution (constructor args > env vars > defaults)
+  _pagination.py   Cursor-based auto-paginating iterators
+  _streaming.py    SSE chat streaming (Vercel AI SDK format)
+  _convenience.py  High-level helpers (get_session, policy setup)
+  _exceptions.py   Exception hierarchy (QuerriError, APIError, etc.)
+```
+
+- **Tests**: [pytest](https://docs.pytest.org/) + [pytest-asyncio](https://pytest-asyncio.readthedocs.io/) with [respx](https://lundberg.github.io/respx/) for HTTP mocking
+- **Type checking**: [mypy](https://mypy-lang.org/) in strict mode
+- **Linting**: [ruff](https://docs.astral.sh/ruff/)
+
+## Submitting changes
+
+1. Create a branch from `main`
+2. Make your changes with clear, descriptive commits
+3. Ensure CI passes:
+   ```sh
+   pytest tests/ -v
+   ruff check querri/ tests/
+   mypy querri/
+   ```
+4. Open a pull request against `main`
+
+## Reporting bugs
+
+Please use the [bug report template](https://github.com/querri-ai/querri-python/issues/new?template=bug_report.md) when filing issues.
+
+## Code of conduct
+
+Be respectful and constructive. We're building something together — treat others the way you'd like to be treated.

querri-1.0.2/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,37 @@
+---
+name: Bug report
+about: Report a bug to help us improve querri
+labels: bug
+---
+
+## Describe the bug
+
+A clear and concise description of what the bug is.
+
+## To reproduce
+
+Steps to reproduce the behavior:
+
+1. Install `querri` version '...'
+2. Call the '...' method
+3. Pass the following options '...'
+4. See error
+
+## Expected behavior
+
+A clear and concise description of what you expected to happen.
+
+## Environment
+
+- **querri version**: [e.g. 0.1.0]
+- **Python version**: [e.g. 3.12.0]
+- **Framework**: [e.g. Django 5, Flask 3, FastAPI 0.110, Plain Python]
+- **OS**: [e.g. macOS 14, Ubuntu 24.04, Windows 11]
+
+## Screenshots
+
+If applicable, add screenshots to help explain the issue.
+
+## Additional context
+
+Add any other context about the problem here.

querri-1.0.2/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,21 @@
+---
+name: Feature request
+about: Suggest an idea for querri
+labels: enhancement
+---
+
+## Is your feature request related to a problem?
+
+A clear and concise description of the problem. E.g. "I'm always frustrated when [...]"
+
+## Describe the solution you'd like
+
+A clear and concise description of what you want to happen.
+
+## Alternatives considered
+
+A clear and concise description of any alternative solutions or features you've considered.
+
+## Additional context
+
+Add any other context or screenshots about the feature request here.

querri-1.0.2/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+## Description
+
+<!-- Summarize your changes and link any related issues (e.g. "Fixes #123"). -->
+
+## Type of change
+
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to change)
+- [ ] Documentation update
+
+## Checklist
+
+- [ ] I have performed a self-review of my code
+- [ ] I have added tests that prove my fix or feature works
+- [ ] `pytest tests/ -v` passes locally
+- [ ] `ruff check querri/ tests/` passes locally
+- [ ] `mypy querri/` passes locally
+- [ ] I have updated documentation if needed

querri-1.0.2/.github/SECURITY.md

@@ -0,0 +1,31 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+If you discover a security vulnerability in `querri`, please report it responsibly.
+
+**Do not open a public issue.** Instead, email **security@querri.com** with:
+
+- A description of the vulnerability
+- Steps to reproduce it
+- The affected version(s)
+
+## Response timeline
+
+- We will acknowledge your report within **48 hours**
+- We will provide an initial assessment and next steps shortly after
+
+## Process
+
+1. Confirm the vulnerability and identify affected versions
+2. Develop and test a fix
+3. Release a patched version
+4. Publicly disclose the issue after the fix is available
+
+## Scope
+
+This policy applies to the `querri` PyPI package. For vulnerabilities in the Querri platform itself, please contact security@querri.com directly.
+
+## Feedback
+
+Suggestions for improving this process are welcome — feel free to open a pull request.

querri-1.0.2/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  pull_request:
+    branches: [main]
+  workflow_call:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check querri/ tests/
+      - run: mypy querri/
+      - run: pytest tests/ -v

querri-1.0.2/.github/workflows/release.yml

@@ -0,0 +1,42 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+*'
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  ci:
+    uses: ./.github/workflows/ci.yml
+
+  release:
+    needs: ci
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: ${{ github.ref_name }}
+          generate_release_notes: true
+          draft: false
+          prerelease: ${{ contains(github.ref_name, '-') }}
+
+  publish:
+    needs: ci
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

querri-1.0.2/.gitignore

@@ -0,0 +1,34 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment variables
+.env
+.env.*
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/

querri-1.0.2/CLAUDE.md

@@ -0,0 +1,93 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Querri Python SDK — a typed Python client for the Querri API, providing both sync (`Querri`) and async (`AsyncQuerri`) clients. Built on httpx + Pydantic v2. Requires Python >=3.9.
+
+## Commands
+
+```bash
+# Install in development mode (includes test + lint + type-check tools)
+pip install -e ".[dev]"
+
+# Run all unit tests
+pytest tests/ -v
+
+# Run a single test file
+pytest tests/test_client.py -v
+
+# Run a single test by name
+pytest tests/ -k "test_name" -v
+
+# Run integration tests (requires QUERRI_API_KEY and QUERRI_ORG_ID env vars)
+pytest tests/test_integration.py -m integration -v
+
+# Type checking
+mypy querri/
+
+# Linting
+ruff check querri/ tests/
+```
+
+## Architecture
+
+### Client Layer
+`Querri` / `AsyncQuerri` (`_client.py`) are the public entry points. They hold lazily-initialized resource namespaces (e.g., `client.users`, `client.projects`) and support context-manager usage. They delegate HTTP to `SyncHTTPClient` / `AsyncHTTPClient` (`_base_client.py`), which handle auth headers (Bearer token + X-Tenant-ID), retries with exponential backoff, and error-to-exception mapping.
+
+### User-Scoped Client
+`UserQuerri` / `AsyncUserQuerri` (`_user_client.py`) are created via `client.as_user(session)`. They use `X-Embed-Session` auth against the internal API (`/api` instead of `/api/v1`). Only expose FGA-filtered resources: `projects`, `dashboards`, `sources`, `data`, `chats`.
+
+### Resource Pattern
+Each API resource lives in `querri/resources/` with paired sync/async classes (e.g., `Users` / `AsyncUsers`). Resources receive the HTTP client at init and expose CRUD methods that return Pydantic models from `querri/types/`. Projects has a nested `Chats` sub-resource for chat streaming.
+
+### Key Subsystems
+- **Pagination** (`_pagination.py`): `SyncCursorPage[T]` / `AsyncCursorPage[T]` — cursor-based with offset fallback, auto-paginating via `__iter__`/`__aiter__`.
+- **Streaming** (`_streaming.py`): `ChatStream` / `AsyncChatStream` — SSE parsing (Vercel AI SDK format: `0:` text, `e:` error, `d:` done).
+- **Convenience** (`_convenience.py`): `get_session()` is the flagship method — resolves/creates a user, applies access policies, and creates an embed session in one call. `client.policies.setup()` creates a policy and assigns users in one call.
+- **Config** (`_config.py`): Constructor args > env vars (`QUERRI_API_KEY`, `QUERRI_ORG_ID`, `QUERRI_HOST`, `QUERRI_TIMEOUT`, `QUERRI_MAX_RETRIES`) > defaults.
+- **Exceptions** (`_exceptions.py`): `QuerriError` → `APIError` (with status-specific subclasses like `RateLimitError`), `StreamError`, `ConfigError`.
+
+## Sync/Async Parity
+
+Every resource, pagination class, and stream has mirrored sync/async implementations. When modifying code:
+- Always change both sync and async variants simultaneously.
+- Async methods use `await` and `async for` but share identical method signatures and return types.
+- In resource files: sync class comes first, async class second.
+- In `_convenience.py`: shared helpers at top, then sync functions, then async functions.
+
+## Adding a New Resource
+
+1. Create type models in `querri/types/<name>.py` — Pydantic `BaseModel` subclasses with `#:` inline field docs.
+2. Create `querri/resources/<name>.py` with paired classes:
+   - `class Foo:` taking `SyncHTTPClient` at `__init__`
+   - `class AsyncFoo:` taking `AsyncHTTPClient` at `__init__`
+   - Both must have full Google-style docstrings (Args/Returns) on every method.
+3. Register lazy properties on both `Querri` and `AsyncQuerri` in `_client.py` (follow the existing deferred-import pattern).
+4. Export new public types in `querri/__init__.py` if needed.
+5. Add tests in `tests/test_<name>.py` using respx mocking.
+
+## Testing Patterns
+
+- Use `@respx.mock` decorator for HTTP mocking.
+- Create a `_make_config()` helper returning `ClientConfig` with test values (`api_key="qk_test"`, `org_id="org_test"`, `base_url="https://test.querri.com/api/v1"`).
+- Instantiate `SyncHTTPClient(_make_config())` or `AsyncHTTPClient(_make_config())` directly.
+- Mock specific URLs: `respx.get("https://test.querri.com/api/v1/endpoint").mock(return_value=httpx.Response(200, json={...}))`.
+- Use `side_effect=[Response1, Response2]` for multi-page pagination tests.
+- pytest-asyncio runs in `auto` mode — no `@pytest.mark.asyncio` decorator needed on async tests.
+- Integration tests are marked `@pytest.mark.integration` and require `QUERRI_API_KEY` + `QUERRI_ORG_ID` env vars.
+
+## Docstring Conventions
+
+- **Style**: Google-style with `Args:`, `Returns:`, `Raises:`, `Example::` sections.
+- **Inline code**: Use double backticks — `` ``value`` ``.
+- **Sync + async**: Both classes get full docstrings with Args/Returns (don't truncate async).
+- **Type model fields**: Use `#:` inline comments on the same line as the field.
+- **Module docstrings**: Every module has a 1-line docstring describing its purpose.
+
+## Code Quality
+
+- **mypy**: Strict mode, target Python 3.9
+- **ruff**: Rules E, F, I, N, UP, B, SIM (target Python 3.9)
+- **Tests**: pytest + pytest-asyncio (mode: auto) + respx for HTTP mocking

querri-1.0.2/PKG-INFO

@@ -0,0 +1,310 @@
+Metadata-Version: 2.4
+Name: querri
+Version: 1.0.2
+Summary: Python SDK and CLI for the Querri data analysis platform
+Project-URL: Homepage, https://querri.com
+Project-URL: Documentation, https://docs.querri.com/sdk/python
+Project-URL: Repository, https://github.com/querri-ai/querri-python
+Author-email: Querri <support@querri.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: pydantic<3.0,>=2.0
+Requires-Dist: typing-extensions>=4.0
+Provides-Extra: cli
+Requires-Dist: pillow<12.0,>=10.0; extra == 'cli'
+Requires-Dist: rich<14.0,>=13.0; extra == 'cli'
+Requires-Dist: typer[all]<1.0,>=0.12; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pillow<12.0,>=10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: rich<14.0,>=13.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: typer[all]<1.0,>=0.12; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Requires-Dist: respx>=0.21; extra == 'test'
+Provides-Extra: tui
+Requires-Dist: pillow<12.0,>=10.0; extra == 'tui'
+Requires-Dist: rich<14.0,>=13.0; extra == 'tui'
+Requires-Dist: typer[all]<1.0,>=0.12; extra == 'tui'
+Description-Content-Type: text/markdown
+
+# Querri — Python SDK and CLI
+
+> **CLI:** Interact with the Querri data analysis platform from the terminal or in scripts.
+> **Python SDK:** Embed Querri analytics in your Python web application with one method call.
+
+## Install
+
+```bash
+pip install querri
+```
+
+---
+
+## CLI Quick Start
+
+The `querri` CLI lets you upload data, create analysis projects, and ask questions — interactively or from scripts.
+
+### Auth
+
+```bash
+querri auth login          # browser-based login
+querri whoami              # confirm who you're logged in as
+```
+
+For scripted/non-interactive use, set `QUERRI_API_KEY` instead of relying on stored tokens:
+
+```bash
+export QUERRI_API_KEY=qk_your_api_key
+export QUERRI_ORG_ID=org_your_org_id
+```
+
+### Example workflow: upload a file and analyze it
+
+```bash
+# Upload a file (CSV, Excel, JSON, etc.)
+querri --json file upload path/to/data.csv
+
+# Create a project
+querri --json project new "My Analysis"
+
+# Add the file to the project (triggers ingestion + agent summary)
+querri --json project add-source <file_id>
+
+# Ask a question
+querri --json project chat -m "What are the top 5 products by revenue?"
+```
+
+For scripting, add `--no-interactive` to prevent prompts and `--json` for parseable output. Note that `--json` and other global flags must come **before** the subcommand:
+
+```bash
+querri --json --no-interactive project chat -m "Summarize the data"   # correct
+querri project chat -m "Summarize the data" --json                    # WRONG
+```
+
+### Self-documenting
+
+The CLI covers all Querri resources — projects, files, sources, views, dashboards, sharing, API keys, users, policies, embed sessions, and more.
+
+```bash
+querri --help
+querri <command> --help
+```
+
+See [`skills/querri-cli/SKILL.md`](skills/querri-cli/SKILL.md) for the full command reference.
+
+---
+
+## Python SDK
+
+For embedding Querri analytics in a Python web application. Use alongside the [`@querri-inc/embed`](https://www.npmjs.com/package/@querri-inc/embed) frontend component.
+
+### Quick Start
+
+```python
+from querri import Querri
+
+client = Querri(api_key="qk_your_api_key", org_id="org_...")
+
+session = client.embed.get_session(
+    user="customer-42",  # external ID from your system
+    ttl=3600,
+)
+
+print(session["session_token"])  # JWT to pass to the frontend
+```
+
+### Wire a session endpoint
+
+**Flask:**
+
+```python
+from flask import Flask, jsonify, request
+from querri import Querri
+
+app = Flask(__name__)
+client = Querri()  # reads QUERRI_API_KEY and QUERRI_ORG_ID from env
+
+@app.route("/api/querri-session", methods=["POST"])
+def querri_session():
+    # Derive user identity from YOUR auth system — never from the request body.
+    auth_user = get_authenticated_user()
+
+    session = client.embed.get_session(
+        user={"external_id": auth_user.id, "email": auth_user.email},
+        access={
+            "sources": ["src_sales_data"],
+            "filters": {"tenant_id": auth_user.tenant_id},
+        },
+        origin=request.headers.get("Origin"),
+        ttl=3600,
+    )
+    return jsonify(session)
+```
+
+Django and FastAPI follow the identical pattern — see **[docs/server-sdk.md](docs/server-sdk.md)** for those examples.
+
+### Add the embed (React)
+
+```tsx
+import { QuerriEmbed } from '@querri-inc/embed/react';
+
+<QuerriEmbed
+  style={{ width: '100%', height: '600px' }}
+  serverUrl="https://app.querri.com"
+  auth={{ sessionEndpoint: '/api/querri-session' }}
+/>
+```
+
+> **Security:** Always derive user identity and access from server-side auth. Never read `user` or `access` from the request body — a malicious client can impersonate any user or escalate access.
+
+### Configuration
+
+The SDK reads configuration from constructor arguments or environment variables:
+
+| Parameter | Env Variable | Default | Description |
+|-----------|-------------|---------|-------------|
+| `api_key` | `QUERRI_API_KEY` | *(required)* | Your `qk_` API key |
+| `org_id` | `QUERRI_ORG_ID` | *(required)* | Organization ID |
+| `host` | `QUERRI_HOST` | `https://app.querri.com` | Server host |
+| `timeout` | `QUERRI_TIMEOUT` | `30.0` | Request timeout (seconds) |
+| `max_retries` | `QUERRI_MAX_RETRIES` | `3` | Retry attempts for transient errors |
+
+> **Note:** The parameter is `host`, not `base_url`. The SDK appends `/api/v1` automatically.
+
+### `get_session()` — Embed Sessions
+
+The flagship convenience method: resolves or creates a user, applies access policies, and generates a session JWT in one call.
+
+```python
+session = client.embed.get_session(
+    user={
+        "external_id": "customer-42",
+        "email": "alice@acme.com",
+        "first_name": "Alice",
+    },
+    access={
+        "sources": ["src_sales_data"],
+        "filters": {
+            "tenant_id": "acme",
+            "region": ["us-east", "us-west"],  # list values are OR'd
+        },
+    },
+    origin="https://app.acme.com",
+    ttl=7200,
+)
+
+session["session_token"]  # str — JWT for the embed
+session["expires_in"]     # int — seconds until expiry
+session["user_id"]        # str — Querri user ID
+```
+
+You can also pass pre-created policy IDs directly:
+
+```python
+session = client.embed.get_session(
+    user={"external_id": "customer-42"},
+    access={"policy_ids": ["pol_abc123"]},
+)
+```
+
+### User-Scoped Client (`as_user`)
+
+```python
+session = client.embed.get_session(user="customer-42", ttl=900)
+
+with client.as_user(session) as user_client:
+    for project in user_client.projects.list():
+        print(project.name)
+```
+
+See **[docs/server-sdk.md](docs/server-sdk.md#user-scoped-client-as_user)** for details on granting access and available resources.
+
+### All Resources
+
+| Resource | Access | Key Methods |
+|----------|--------|-------------|
+| `client.dashboards` | Dashboard management | `list`, `create`, `get`, `update`, `delete`, `refresh` |
+| `client.projects` | Analysis projects | `list`, `create`, `get`, `run`, `run_status`, `list_steps` |
+| `client.projects.chats` | Chats within projects | `create`, `list`, `stream`, `cancel`, `delete` |
+| `client.sources` | Sources, connectors & data | `list`, `create`, `create_data_source`, `query`, `source_data`, `append_rows`, `replace_data`, `ask`, `sync`, `list_connectors` |
+| `client.views` | SQL-defined views | `list`, `create`, `get`, `update`, `delete`, `run`, `preview`, `chat` |
+| `client.files` | File management | `upload`, `list`, `get`, `delete` |
+| `client.users` | User management | `list`, `create`, `get`, `update`, `delete` |
+| `client.keys` | API key management | `create`, `list`, `get`, `delete` |
+| `client.audit` | Audit log | `list` |
+| `client.usage` | Usage metrics | `org_usage`, `user_usage` |
+| `client.sharing` | Sharing & permissions | `share_project`, `share_dashboard`, `share_source` |
+
+### Async Client
+
+`AsyncQuerri` mirrors the sync API with `async`/`await`:
+
+```python
+from querri import AsyncQuerri
+
+async with AsyncQuerri() as client:
+    session = await client.embed.get_session(
+        user={"external_id": "cust-42", "email": "a@b.com"},
+        access={"sources": ["src_sales"]},
+    )
+```
+
+### Error Handling
+
+All errors extend `QuerriError`:
+
+```
+QuerriError
+├── APIError                — HTTP error responses
+│   ├── ValidationError     — 400
+│   ├── AuthenticationError — 401
+│   ├── PermissionError     — 403
+│   ├── NotFoundError       — 404
+│   ├── ConflictError       — 409
+│   ├── RateLimitError      — 429 (auto-retried)
+│   └── ServerError         — 5xx (auto-retried)
+├── StreamError             — SSE stream issues
+└── ConfigError             — missing/invalid configuration
+```
+
+The SDK automatically retries **429** (always) and **5xx** (idempotent methods only) with exponential backoff + jitter.
+
+### Full Reference
+
+See **[docs/server-sdk.md](docs/server-sdk.md)** for complete method signatures, all framework examples, and the `get_session()` deep dive.
+
+---
+
+## Requirements
+
+- Python 3.10+
+- [`httpx`](https://www.python-httpx.org/) >= 0.27
+- [`pydantic`](https://docs.pydantic.dev/) >= 2.0
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+pytest tests/test_integration.py -m integration -v  # requires API credentials
+```
+
+## License
+
+MIT