querri 1.0.2__py3-none-any.whl

querri/types/usage.py

@@ -0,0 +1,39 @@
+"""Usage type models for the Querri SDK."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class DailyUsage(BaseModel):
+    """Single day's usage count."""
+
+    date: str  #: Date string (YYYY-MM-DD).
+    count: int = 0  #: Number of AI messages on this date.
+
+
+class OrgUsageReport(BaseModel):
+    """Organization-level usage report."""
+
+    org_id: str | None = None  #: Organization ID.
+    period: str | None = None  #: Period name (current_month, last_month, last_30_days).
+    period_start: str | None = None  #: ISO-8601 start of the reporting period.
+    period_end: str | None = None  #: ISO-8601 end of the reporting period.
+    total_ai_messages: int | None = None  #: Total AI messages in the period.
+    active_user_count: int | None = None  #: Number of active users in the period.
+    project_count: int | None = None  #: Number of projects in the organization.
+
+
+class UserUsageReport(BaseModel):
+    """Per-user usage report."""
+
+    user_id: str | None = None  #: User ID.
+    period: str | None = None  #: Period name.
+    period_start: str | None = None  #: ISO-8601 start of the reporting period.
+    period_end: str | None = None  #: ISO-8601 end of the reporting period.
+    ai_messages: int | None = None  #: Total AI messages by this user.
+    daily_breakdown: list[DailyUsage] | None = None  #: Daily message counts.
+
+
+# Keep backward compat alias
+UsageReport = OrgUsageReport

querri/types/user.py

@@ -0,0 +1,33 @@
+"""User type models for the Querri SDK."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class User(BaseModel):
+    """A user in the Querri organization."""
+
+    id: str  #: Unique user identifier.
+    email: str  #: User's email address.
+    first_name: str | None = None  #: User's first name.
+    last_name: str | None = None  #: User's last name.
+    role: str = "member"  #: Role, e.g. ``"admin"`` or ``"member"``.
+    external_id: str | None = None  #: Caller-supplied external identifier.
+    created_at: str | None = None  #: ISO-8601 timestamp of creation.
+    created: bool | None = None  #: Only on get_or_create; ``True`` if newly created.
+
+
+class UserDeleteResponse(BaseModel):
+    """Response from deleting a user."""
+
+    id: str  #: ID of the deleted user.
+    deleted: bool = True  #: Whether the user was successfully deleted.
+
+
+class ExternalIdDeleteResponse(BaseModel):
+    """Response from removing an external ID mapping."""
+
+    external_id: str  #: The external ID that was removed.
+    user_id: str  #: The user ID that was unlinked.
+    deleted: bool  #: Whether the mapping was deleted.

querri-1.0.2.dist-info/METADATA

@@ -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

querri-1.0.2.dist-info/RECORD

@@ -0,0 +1,64 @@
+querri/__init__.py,sha256=Fc27eNSwFmuIzGWxD4UDblANJfbGlkTvoVtXeg2uc04,1170
+querri/_auth.py,sha256=BBJD-EE09AGeWiSRq67NaRh-A6Qpuz2PSQ8oaDweiNU,28360
+querri/_base_client.py,sha256=dMGlV2X_KyF_RhGL91jDROnLrRnG0fKqB4agb0nUSps,13336
+querri/_client.py,sha256=H6E5fX4TCGS_1DN8h-YDfYwGQ4116SAngKhMehsALH0,13196
+querri/_config.py,sha256=1eNoGoN3rd1gFYa5HwCvhXno6Uz4NEfmyIAPJHUgALg,5218
+querri/_convenience.py,sha256=TC-ggHPHgq07K_0kFSYUdf-D0VUKqrNCzRpGGmVAL-s,18785
+querri/_exceptions.py,sha256=sHFdAc2lNPby6Bnej5GgwLmcm05ag59GCWdw4gllQgg,4849
+querri/_pagination.py,sha256=d8bxpzGNLvDfJq7qwgWY8as31DWYfpm8RJPjauM4ofA,8723
+querri/_streaming.py,sha256=8KgXjt1VXWz8wXpw1lhl5Sqc9oDiwH88TFwTRNatxAU,23407
+querri/_user_client.py,sha256=ARN99plfuiV9bnL0ig5NiI44MOyNZ1tBFEOiBHa4VaU,6569
+querri/_version.py,sha256=Zn1KFblwuFHiDRdRAiRnDBRkbPttWh44jKa5zG2ov0E,22
+querri/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+querri/cli/__init__.py,sha256=S3IQjFvKO2PdkzIGJUCuTK3a7XTDh7EwDaRJGCVfGzE,663
+querri/cli/_app.py,sha256=Wqj0pmJoPFihY-rZhes0ulCKgTAgmJT6vqXZrBSUI1o,8223
+querri/cli/_context.py,sha256=7y2HBVm1A_oEs6OEfMU-_rxOMA5V0frwsCZEJ8a6i6o,6932
+querri/cli/_image.py,sha256=Mf5xzWJOFB-G44oPGILE4XwIFjfaMW7K7vu3DFK5oUc,7241
+querri/cli/_output.py,sha256=y_YxY7SVKyF3YKzxMDeTVUX-AtEhLjIKPgpiotHFfe8,8625
+querri/cli/audit.py,sha256=Ko1jJw1LiX0yWzVZ74wOSR7djyDeR4SXQvttmYTSNiY,1999
+querri/cli/auth.py,sha256=ZockvJ0DdDzIXBNLS2inp22gWk5q9sh0vW-lMpJX80s,17466
+querri/cli/chat.py,sha256=B6zKt7Y-uzVQeK1b6-R5MU16iOlT49QS1TpZUhgsE78,43395
+querri/cli/chats.py,sha256=KH3JMZXruZBw7EaxeRidYUBswx9s9nbfoEvhty-0Cao,10857
+querri/cli/dashboards.py,sha256=u4D3CEpyCBo0YJxSBPlOMmzhQj4esZcwJZcav1Jf618,9367
+querri/cli/embed.py,sha256=onuBPL8zQBLzq9K3SiMzPH3vvNTNOnQjitzJy0gts2g,6747
+querri/cli/files.py,sha256=bEXAu7lhATLc0WabndJkMMp2C0JVWYY5WC06UIJ5gtg,6222
+querri/cli/keys.py,sha256=zfgMdh3at_c3byL_G3FzMHYqew7VFb4Zt33jdJ3b4f0,9740
+querri/cli/policies.py,sha256=IcmPdQnwZ64xFZGDscn08IVhLek5HvsqQ0mAYqzw5uw,13725
+querri/cli/projects.py,sha256=KxRZpzIThGdhgzXWvIqakAUZSJyIEVJ7XpqLxijO628,29531
+querri/cli/sharing.py,sha256=L1WbJEZYuDltbv99EO3MdkSuyWuNpKijc9jqYp3PWSQ,12874
+querri/cli/sources.py,sha256=7yAr2hMe60w6ZChfEcAEb1pxmdf0SintSa_-4wd3jcA,17455
+querri/cli/steps.py,sha256=ABRaI9FglWU2JNNE7Hol111Uf_VT4wlPLHoZqUQiS7M,3750
+querri/cli/usage.py,sha256=7R2xlsICs6hL_ybBCH4sqhphh1pK0rjryN8uJoX20Yk,2877
+querri/cli/users.py,sha256=VqelrgxE4k0e6Ar7kno6tckrHskeWqVHktJk-vrH-Q8,6858
+querri/cli/views.py,sha256=2WtRHR690Ai0EEiST1fle02IZ6i1tobSynPSeavoyBg,15263
+querri/cli/whoami.py,sha256=1WBm6BjqfMIgUZ06LVd1NYA616VqQYaPjgotgtJjtjA,2354
+querri/resources/__init__.py,sha256=MwTB3luMZE6pE7RX6ZI2pY2pLNzKuIJYeAXt__luRbA,43
+querri/resources/audit.py,sha256=sts0EgdCpxoL-cUn-QLlYelDJBQN_MIOQyxO6WFklCU,3796
+querri/resources/dashboards.py,sha256=z5gIaow_EHXMdt97o9ENK5jKZ1cKdnWHkKMAe72-wl4,9070
+querri/resources/embed.py,sha256=IeWfF-w8W5O3sV-5gzduf1nvNUod3pCiS-D9pohmJoU,8827
+querri/resources/files.py,sha256=AM3RKyURMbOoHvzRmDsPEEsQuLkbTmiD2EIqdUiuKu8,3796
+querri/resources/keys.py,sha256=a8oBa0hamQcKBKECPBfwL2_epHeOwZRYtz-a5aZRNwA,6472
+querri/resources/policies.py,sha256=x9MKaZ5YkHMrN3HJ0a77KE26us9LZua6Qnc2SPlyZHE,15809
+querri/resources/projects.py,sha256=ODB8Oe6tdQKZ_zHLq1B0QDPrK35ce1o4SZ4z9-KAAzE,23922
+querri/resources/sharing.py,sha256=AlGoXdgAIQc5M3wQ4yIOXuPmJFIoZLhkRVAiF2mZeEU,10811
+querri/resources/sources.py,sha256=gb-oQL2g2nttSFapTi0A_QqlK6y6YIyqxUE0LP4KbXc,15655
+querri/resources/usage.py,sha256=3U1Y1_Xq3xz4FOTDEGsgw90xGkZhF5FZeZP2GIOv8fQ,2809
+querri/resources/users.py,sha256=MryXKhk-8gls_Iv5PkDSfyZqHEPIvIQv7kb0Grc-5Kw,10078
+querri/resources/views.py,sha256=leCa2Ddlmx7t54IGwPZPfaPbqnRaMTNzI9LIy-Am6Pw,10574
+querri/types/__init__.py,sha256=NeamK9nIm1-dryYlObbCEonKFO6EamBfmVCme1PbNiE,2283
+querri/types/audit.py,sha256=0MTYRW1LNyotauC03-jfAgfJ4Kb3w90zkbsSbEn8rfs,848
+querri/types/chat.py,sha256=jM9Y2pMIFKrMeOR1fRU9rox2xE6qqpDnO6LCj-lGtjg,1679
+querri/types/dashboard.py,sha256=Os2DAdn92ZPY26Kpf710uS3EdlL_kp9HpSZvdfjbQtM,1778
+querri/types/data.py,sha256=Bc7L4ocINTlzmYeaQ2L7ZuQs085QAdko2WwpR9R_6d4,2140
+querri/types/embed.py,sha256=m35FYj8QVA51zc54NwsVV_-PvpzAKDjem6-JHDRLnsg,1413
+querri/types/file.py,sha256=ry5LRwdZ0qdFK-MQNc5jm7EWXWPwY_0H-WcshaMlYNk,648
+querri/types/key.py,sha256=t4XtoDC1euNYa_rA07BdaF8DeMxRCoWNQ2EHR5nte3Q,1447
+querri/types/policy.py,sha256=mcdMrSdSWbDqbTcU21A6gx0fHz7xiP8E6XiOvtNT4HI,3714
+querri/types/project.py,sha256=QI64T3-7iNbvKemIDtiSxILt0Nc42KWnO1APkPaHieA,6250
+querri/types/sharing.py,sha256=6N0VauTTa28Jju17XviiPUPWlEokfwc8ZFAb5ewHCUE,717
+querri/types/usage.py,sha256=3otZESeR_ZlVH2KdvP3HguS9UaESDDyn6hHPCIqkQ_8,1426
+querri/types/user.py,sha256=4CBdvbjJCerjiqI8GkgtUo9qkJ9sqAWPofbMCf0geoI,1138
+querri-1.0.2.dist-info/METADATA,sha256=Zan9UnB8MrRlmUnxlWmW8nykbIDPfNYXNnrcld0Eq0Y,10018
+querri-1.0.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+querri-1.0.2.dist-info/entry_points.txt,sha256=G88OLZu2u5pXTQkGP5obbK9pwFMoNMGpfWrvXQTVWXA,42
+querri-1.0.2.dist-info/RECORD,,

querri-1.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

querri-1.0.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+querri = querri.cli:app