querri 1.0.2__py3-none-any.whl

querri/_user_client.py

@@ -0,0 +1,193 @@
+"""User-scoped client that uses embed session auth and FGA-filtered resources.
+
+Calls the internal API (``/api``) instead of the public API (``/api/v1``).
+Resources are automatically filtered by the session user's access policies.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Any
+
+from ._base_client import AsyncHTTPClient, SyncHTTPClient
+from ._config import ClientConfig
+
+if TYPE_CHECKING:
+    from .resources.dashboards import AsyncDashboards, Dashboards
+    from .resources.projects import AsyncChats, AsyncProjects, Chats, Projects
+    from .resources.sources import AsyncSources, Sources
+
+
+def _session_config(
+    session: dict[str, Any], parent_config: ClientConfig
+) -> ClientConfig:
+    """Build a config for session-mode HTTP clients.
+
+    Derives the ``/api`` base URL from the parent's ``/api/v1`` URL and
+    sets the session token for ``X-Embed-Session`` auth.
+    """
+    # Strip /api/v1 suffix to get the host, then append /api
+    host = re.sub(r"/api/v1$", "", parent_config.base_url)
+    return ClientConfig(
+        api_key="",  # Not used in session mode.
+        org_id="",  # Not used in session mode.
+        base_url=f"{host}/api",
+        timeout=parent_config.timeout,
+        max_retries=parent_config.max_retries,
+        session_token=session["session_token"],
+    )
+
+
+class UserQuerri:
+    """User-scoped synchronous client with FGA-filtered resources.
+
+    Calls the internal API (``/api``) using an embed session token.
+    Only exposes resources visible to the session user.
+
+    Usage::
+
+        session = client.embed.get_session(user="ext_123")
+        user_client = client.as_user(session)
+        for project in user_client.projects.list():
+            print(project.name)
+
+    Create via :meth:`Querri.as_user`.
+    """
+
+    def __init__(self, session: dict[str, Any], parent_config: ClientConfig) -> None:
+        """Initialize with session token and parent client config.
+
+        Args:
+            session: Result from ``get_session()`` containing ``session_token``.
+            parent_config: Config from the parent ``Querri`` client.
+        """
+        self._config = _session_config(session, parent_config)
+        self._http = SyncHTTPClient(self._config)
+
+        # Resource namespaces — lazily initialized on first access.
+        # Deferred imports keep client creation fast and avoid circular imports.
+        self._projects: object | None = None
+        self._dashboards: object | None = None
+        self._sources: object | None = None
+        self._chats: object | None = None
+
+    @property
+    def projects(self) -> Projects:
+        if self._projects is None:
+            from .resources.projects import Projects
+
+            self._projects = Projects(self._http)
+        return self._projects  # type: ignore[return-value]
+
+    @property
+    def dashboards(self) -> Dashboards:
+        if self._dashboards is None:
+            from .resources.dashboards import Dashboards
+
+            self._dashboards = Dashboards(self._http)
+        return self._dashboards  # type: ignore[return-value]
+
+    @property
+    def sources(self) -> Sources:
+        if self._sources is None:
+            from .resources.sources import Sources
+
+            self._sources = Sources(self._http)
+        return self._sources  # type: ignore[return-value]
+
+    @property
+    def chats(self) -> Chats:
+        if self._chats is None:
+            from .resources.projects import Chats
+
+            self._chats = Chats(self._http)
+        return self._chats  # type: ignore[return-value]
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._http.close()
+
+    def __enter__(self) -> UserQuerri:
+        """Enter context manager for automatic resource cleanup."""
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        """Close the HTTP client on context manager exit."""
+        self.close()
+
+
+class AsyncUserQuerri:
+    """User-scoped asynchronous client with FGA-filtered resources.
+
+    Calls the internal API (``/api``) using an embed session token.
+    Only exposes resources visible to the session user.
+
+    Usage::
+
+        session = await client.embed.get_session(user="ext_123")
+        user_client = client.as_user(session)
+        async for project in user_client.projects.list():
+            print(project.name)
+
+    Create via :meth:`AsyncQuerri.as_user`.
+    """
+
+    def __init__(self, session: dict[str, Any], parent_config: ClientConfig) -> None:
+        """Initialize with session token and parent client config.
+
+        Args:
+            session: Result from ``get_session()`` containing ``session_token``.
+            parent_config: Config from the parent ``AsyncQuerri`` client.
+        """
+        self._config = _session_config(session, parent_config)
+        self._http = AsyncHTTPClient(self._config)
+
+        # Resource namespaces — lazily initialized on first access.
+        self._projects: object | None = None
+        self._dashboards: object | None = None
+        self._sources: object | None = None
+        self._chats: object | None = None
+
+    @property
+    def projects(self) -> AsyncProjects:
+        if self._projects is None:
+            from .resources.projects import AsyncProjects
+
+            self._projects = AsyncProjects(self._http)
+        return self._projects  # type: ignore[return-value]
+
+    @property
+    def dashboards(self) -> AsyncDashboards:
+        if self._dashboards is None:
+            from .resources.dashboards import AsyncDashboards
+
+            self._dashboards = AsyncDashboards(self._http)
+        return self._dashboards  # type: ignore[return-value]
+
+    @property
+    def sources(self) -> AsyncSources:
+        if self._sources is None:
+            from .resources.sources import AsyncSources
+
+            self._sources = AsyncSources(self._http)
+        return self._sources  # type: ignore[return-value]
+
+    @property
+    def chats(self) -> AsyncChats:
+        if self._chats is None:
+            from .resources.projects import AsyncChats
+
+            self._chats = AsyncChats(self._http)
+        return self._chats  # type: ignore[return-value]
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._http.close()
+
+    async def __aenter__(self) -> AsyncUserQuerri:
+        """Enter async context manager for automatic resource cleanup."""
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        """Close the HTTP client on async context manager exit."""
+        await self.close()

querri/_version.py

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

querri/cli/__init__.py

@@ -0,0 +1,21 @@
+"""Querri CLI — command-line interface for the Querri data analysis platform.
+
+Entry point guard: if typer is not installed, prints a clean error message
+and exits with code 1. No tracebacks, no file paths, no module names.
+"""
+
+from __future__ import annotations
+
+
+def app() -> None:
+    """Entry point registered in pyproject.toml as ``querri = "querri.cli:app"``."""
+    try:
+        from querri.cli._app import main_app
+
+        main_app()
+    except ImportError:
+        import sys
+
+        print("Querri CLI requires additional dependencies.", file=sys.stderr)
+        print("Install with: pip install 'querri[cli]'", file=sys.stderr)
+        sys.exit(1)

querri/cli/_app.py

@@ -0,0 +1,246 @@
+"""Main Typer application with global options and sub-app registration."""
+
+from __future__ import annotations
+
+import sys
+
+import typer
+
+from querri._version import __version__
+from querri.cli.audit import audit_app
+from querri.cli.auth import auth_app
+from querri.cli.chats import chats_app
+from querri.cli.dashboards import dashboards_app
+from querri.cli.embed import embed_app
+from querri.cli.files import files_app
+from querri.cli.keys import keys_app
+from querri.cli.policies import policies_app
+from querri.cli.projects import projects_app
+from querri.cli.sharing import sharing_app
+from querri.cli.sources import sources_app
+from querri.cli.steps import steps_app
+from querri.cli.usage import usage_app
+from querri.cli.users import users_app
+from querri.cli.views import view_app
+from querri.cli.whoami import whoami_app
+
+# ---------------------------------------------------------------------------
+# TTY detection — drives output behavior across the CLI
+# ---------------------------------------------------------------------------
+
+IS_INTERACTIVE = sys.stdout.isatty()
+
+
+# ---------------------------------------------------------------------------
+# Main app
+# ---------------------------------------------------------------------------
+
+main_app = typer.Typer(
+    name="querri",
+    help=(
+        "[bold #f15a24]Querri CLI[/bold #f15a24] — command-line interface for the "
+        "[#f15a24]Querri[/#f15a24] data analysis platform.\n\n"
+        "Get started:\n"
+        "  [#f15a24]querri auth login[/#f15a24]"
+        "                    Authenticate via browser\n"
+        "  [#f15a24]querri project new[/#f15a24]"
+        "                   Create a new project\n"
+        "  [#f15a24]querri file upload data.csv[/#f15a24]          Upload a data file\n"
+        '  [#f15a24]querri project chat -m "analyze this"[/#f15a24]'
+        '  Chat with your data'
+    ),
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+    pretty_exceptions_enable=False,
+)
+
+
+# ---------------------------------------------------------------------------
+# Version callback
+# ---------------------------------------------------------------------------
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        if IS_INTERACTIVE:
+            from rich.console import Console
+
+            Console(stderr=True).print(
+                f"[bold #f15a24]querri[/bold #f15a24] {__version__}"
+            )
+        else:
+            print(f"querri {__version__}")
+        raise typer.Exit()
+
+
+# ---------------------------------------------------------------------------
+# Global options callback
+# ---------------------------------------------------------------------------
+
+
+@main_app.callback()
+def _global_options(
+    ctx: typer.Context,
+    host: str | None = typer.Option(
+        None,
+        "--host",
+        envvar="QUERRI_HOST",
+        help="Querri server host (default: https://app.querri.com).",
+        show_default=False,
+    ),
+    api_key: str | None = typer.Option(
+        None,
+        "--api-key",
+        envvar="QUERRI_API_KEY",
+        help="API key (prefer QUERRI_API_KEY env var).",
+        show_default=False,
+    ),
+    org_id: str | None = typer.Option(
+        None,
+        "--org-id",
+        envvar="QUERRI_ORG_ID",
+        help="Organization ID.",
+        show_default=False,
+    ),
+    profile: str | None = typer.Option(
+        None,
+        "--profile",
+        help="Named auth profile (v0.2.1+).",
+        hidden=True,
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output as JSON.",
+    ),
+    quiet: bool = typer.Option(
+        False,
+        "--quiet",
+        "-q",
+        help="Minimal output (IDs only).",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Verbose output.",
+    ),
+    interactive: bool | None = typer.Option(
+        None,
+        "--interactive/--no-interactive",
+        help="Force interactive/non-interactive mode.",
+        show_default=False,
+    ),
+    project: str | None = typer.Option(
+        None,
+        "--project",
+        "-p",
+        envvar="QUERRI_PROJECT_ID",
+        help="Project ID (overrides active project).",
+        show_default=False,
+    ),
+    chat: str | None = typer.Option(
+        None,
+        "--chat",
+        envvar="QUERRI_CHAT_ID",
+        help="Chat ID (overrides active chat).",
+        show_default=False,
+    ),
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
+    """[#f15a24]Querri CLI[/#f15a24] — manage projects,
+    data, and AI chats from the terminal."""
+    # Determine interactive mode
+    is_interactive = interactive if interactive is not None else IS_INTERACTIVE
+
+    # Warn about --api-key in shell history (only in interactive TTY mode)
+    if api_key and is_interactive:
+        import sys as _sys
+
+        print(
+            "Warning: API key passed as command argument may appear in shell history. "
+            "Consider using QUERRI_API_KEY env var instead.",
+            file=_sys.stderr,
+        )
+
+    # Store options in context for downstream commands
+    ctx.ensure_object(dict)
+    ctx.obj["host"] = host
+    ctx.obj["api_key"] = api_key
+    ctx.obj["org_id"] = org_id
+    ctx.obj["profile"] = profile
+    ctx.obj["project"] = project
+    ctx.obj["chat"] = chat
+    ctx.obj["json"] = json_output
+    ctx.obj["quiet"] = quiet
+    ctx.obj["verbose"] = verbose
+    ctx.obj["interactive"] = is_interactive
+
+
+# ---------------------------------------------------------------------------
+# Sub-app registration with rich_help_panel groupings
+# ---------------------------------------------------------------------------
+
+# ── Getting Started ──────────────────────────────────────────────────────
+main_app.add_typer(
+    auth_app, name="auth", rich_help_panel="[#f15a24]Getting Started[/#f15a24]"
+)
+main_app.add_typer(
+    whoami_app, name="whoami", rich_help_panel="[#f15a24]Getting Started[/#f15a24]"
+)
+
+# ── Projects & Data ─────────────────────────────────────────────────────
+main_app.add_typer(
+    projects_app, name="project", rich_help_panel="[#f15a24]Projects & Data[/#f15a24]"
+)
+main_app.add_typer(
+    chats_app, name="chat", rich_help_panel="[#f15a24]Projects & Data[/#f15a24]"
+)
+main_app.add_typer(
+    steps_app, name="step", rich_help_panel="[#f15a24]Projects & Data[/#f15a24]"
+)
+main_app.add_typer(
+    files_app, name="file", rich_help_panel="[#f15a24]Projects & Data[/#f15a24]"
+)
+main_app.add_typer(
+    sources_app, name="source", rich_help_panel="[#f15a24]Projects & Data[/#f15a24]"
+)
+main_app.add_typer(
+    view_app, name="view", rich_help_panel="[#f15a24]Projects & Data[/#f15a24]"
+)
+main_app.add_typer(
+    dashboards_app,
+    name="dashboard",
+    rich_help_panel="[#f15a24]Projects & Data[/#f15a24]",
+)
+
+# ── Administration ──────────────────────────────────────────────────────
+main_app.add_typer(
+    users_app, name="user", rich_help_panel="[#f15a24]Administration[/#f15a24]"
+)
+main_app.add_typer(
+    keys_app, name="key", rich_help_panel="[#f15a24]Administration[/#f15a24]"
+)
+main_app.add_typer(
+    policies_app, name="policy", rich_help_panel="[#f15a24]Administration[/#f15a24]"
+)
+main_app.add_typer(
+    sharing_app, name="share", rich_help_panel="[#f15a24]Administration[/#f15a24]"
+)
+
+# ── Advanced ────────────────────────────────────────────────────────────
+main_app.add_typer(
+    embed_app, name="session", rich_help_panel="[#f15a24]Advanced[/#f15a24]"
+)
+main_app.add_typer(
+    usage_app, name="usage", rich_help_panel="[#f15a24]Advanced[/#f15a24]"
+)
+main_app.add_typer(
+    audit_app, name="audit", rich_help_panel="[#f15a24]Advanced[/#f15a24]"
+)

querri/cli/_context.py

@@ -0,0 +1,216 @@
+"""CLI context helpers — construct SDK clients from CLI args and env vars."""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import TYPE_CHECKING, Any
+
+import typer
+
+if TYPE_CHECKING:
+    from querri._auth import TokenProfile
+
+from querri._client import Querri
+from querri._exceptions import ConfigError
+
+
+def get_client(ctx: typer.Context) -> Querri:
+    """Construct a Querri client from CLI context options.
+
+    Resolution order:
+    1. Explicit ``--api-key`` flag (wins)
+    2. Environment variables (``QUERRI_API_KEY``, ``QUERRI_ACCESS_TOKEN``)
+    3. Token store (``~/.querri/tokens.json`` — active profile, auto-refresh)
+    4. Error with guidance
+
+    Returns:
+        Configured ``Querri`` client instance.
+
+    Raises:
+        typer.Exit: With code 2 on authentication/config errors.
+    """
+    obj: dict[str, Any] = ctx.ensure_object(dict)
+
+    # 1. Explicit --api-key wins
+    api_key = obj.get("api_key")
+    org_id = obj.get("org_id")
+    host = obj.get("host")
+
+    if api_key:
+        try:
+            return Querri(api_key=api_key, org_id=org_id, host=host)
+        except ConfigError as exc:
+            _handle_config_error(obj, exc)
+            raise typer.Exit(code=2) from None
+
+    # 2. Environment variables — let resolve_config handle them
+    if os.environ.get("QUERRI_API_KEY") or os.environ.get("QUERRI_ACCESS_TOKEN"):
+        try:
+            return Querri(org_id=org_id, host=host)
+        except ConfigError as exc:
+            _handle_config_error(obj, exc)
+            raise typer.Exit(code=2) from None
+
+    # 3. Token store — load active profile, auto-refresh if needed
+    try:
+        from querri._auth import TokenStore, needs_refresh, refresh_tokens
+        from querri._config import DEFAULT_HOST
+
+        profile_name = obj.get("profile") or "default"
+        store = TokenStore.load()
+        profile = store.profiles.get(profile_name)
+
+        if profile and profile.access_token:
+            # Use the host stored in the profile (from login), CLI flag, env, or default
+            resolved_host = (
+                host or os.environ.get("QUERRI_HOST") or profile.host or DEFAULT_HOST
+            )
+
+            # Auto-refresh if near expiry
+            if needs_refresh(profile):
+                try:
+                    profile = refresh_tokens(profile, resolved_host)
+                    store.save_profile(profile_name, profile)
+                except Exception:
+                    # Refresh failed (RuntimeError, timeout, network error, etc.)
+                    # but the token may still be valid — needs_refresh fires
+                    # early as a buffer. Fall through to use it anyway.
+                    pass
+
+            return Querri(
+                access_token=profile.access_token,
+                org_id=profile.org_id or org_id,
+                host=resolved_host,
+            )
+    except Exception as exc:
+        # Token store error — print debug info in verbose mode and fall through
+        if obj.get("verbose"):
+            print(f"Token store error: {exc}", file=sys.stderr)
+        pass
+
+    # 4. Nothing worked
+    _handle_config_error(
+        obj,
+        ConfigError(
+            "No credentials found. Run 'querri auth login' or set QUERRI_API_KEY."
+        ),
+    )
+    raise typer.Exit(code=2)
+
+
+def _handle_config_error(obj: dict[str, Any], exc: ConfigError) -> None:
+    """Print a user-friendly config error message."""
+    is_json = obj.get("json", False)
+
+    if is_json:
+        import json
+
+        error_obj = {
+            "error": "auth_failed",
+            "message": str(exc),
+            "hint": "Run 'querri auth login' or set QUERRI_API_KEY and QUERRI_ORG_ID "
+            "environment variables.",
+            "code": 2,
+        }
+        print(json.dumps(error_obj))
+    else:
+        from querri.cli._output import print_error
+
+        print_error(str(exc))
+        print(
+            "\nTo get started:\n"
+            "  querri auth login            # Browser-based login\n"
+            "  export QUERRI_API_KEY=qk_...  # API key auth\n"
+            "  export QUERRI_ORG_ID=org_...\n"
+            "\nOr pass them as flags:\n"
+            "  querri --api-key qk_... --org-id org_... <command>",
+            file=sys.stderr,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Workspace state helpers
+# ---------------------------------------------------------------------------
+
+
+def _get_profile(ctx: typer.Context) -> TokenProfile | None:
+    """Load the active TokenProfile (or None)."""
+    from querri._auth import TokenStore
+
+    obj = ctx.ensure_object(dict)
+    profile_name = obj.get("profile") or "default"
+    store = TokenStore.load()
+    return store.profiles.get(profile_name)
+
+
+def _save_profile(ctx: typer.Context, profile: "TokenProfile") -> None:
+    """Persist updates to the active TokenProfile."""
+    from querri._auth import TokenStore
+
+    obj = ctx.ensure_object(dict)
+    profile_name = obj.get("profile") or "default"
+    store = TokenStore.load()
+    store.save_profile(profile_name, profile)
+
+
+def resolve_project_id(ctx: typer.Context) -> str:
+    """Resolve project ID from --project flag → stored state → error."""
+    obj = ctx.ensure_object(dict)
+    is_json = obj.get("json", False)
+
+    # 1. Explicit --project flag
+    project: str | None = obj.get("project")
+    if project:
+        return project
+
+    # 2. Stored active project
+    profile = _get_profile(ctx)
+    if profile and profile.active_project_id:
+        return str(profile.active_project_id)
+
+    # 3. Error
+    from querri.cli._output import print_error
+
+    if is_json:
+        from querri.cli._output import print_json_error
+
+        print_json_error(
+            "no_project",
+            "No active project. Run 'querri project select <name>' or pass --project.",
+            1,
+        )
+    else:
+        print_error(
+            "No active project.\n"
+            "  querri project select <name>   # Set active project\n"
+            "  querri project new             # Create a new project\n"
+            "  --project <id>                 # Pass explicitly"
+        )
+    raise typer.Exit(code=1)
+
+
+def resolve_user_id(ctx: typer.Context) -> str:
+    """Resolve user ID from env → stored profile → error."""
+    env_user = os.environ.get("QUERRI_USER_ID")
+    if env_user:
+        return env_user
+
+    profile = _get_profile(ctx)
+    if profile and profile.user_id:
+        return str(profile.user_id)
+
+    obj = ctx.ensure_object(dict)
+    from querri.cli._output import print_error
+
+    if obj.get("json"):
+        from querri.cli._output import print_json_error
+
+        print_json_error("no_user_id", "Could not determine user ID.", 1)
+    else:
+        print_error(
+            "Could not determine user ID. "
+            "Set QUERRI_USER_ID or log in with "
+            "'querri auth login'."
+        )
+    raise typer.Exit(code=1)