querri 2.0.0__tar.gz → 2.1.0__tar.gz

{querri-2.0.0 → querri-2.1.0}/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 2.1.0 (2026-09-24)
+
+### Added
+
+- **`client.library`** (sync and async) and the `querri library` CLI: the Data
+  Library surface — libraries, collections, anchor and refining questions,
+  graph search and zoom, `record_fact`, the Librarian `chat` / `chat_stream`,
+  `ask`, `intake`, `consolidate`, `eval`, backfill and health. Reference:
+  [docs/data-library.md](docs/data-library.md). This is the `dev` line that
+  had been building since 1.1.0; it ships here unchanged.
+
+### Fixed
+
+- **Error bodies without a Stripe-style envelope keep their message and
+  code.** FastAPI raises `{"detail": {"error": {...}}}` (or a plain string
+  `detail`); `APIError.message`, `.code` and `.type` were left as
+  `"HTTP <status>"` / `None` for those, so a `NotFoundError` for a step with
+  no data read the same as one for a missing project. Both shapes are parsed
+  now.
+
 ## 2.0.0 (2026-08-31)
 
 Migration guide with before/after snippets: [docs/MIGRATION.md](docs/MIGRATION.md).

{querri-2.0.0 → querri-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: querri
-Version: 2.0.0
+Version: 2.1.0
 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
@@ -290,6 +290,7 @@ See **[docs/server-sdk.md](docs/server-sdk.md#user-scoped-client-as_user)** for
 | `client.projects.chats` | Chats within projects | `create`, `list`, `get`, `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`, `get_run`, `wait_for_run`, `preview`, `chat` |
+| `client.library` | Data Library — graph + librarian agent | `create_library`, `create_collection`, `create_anchor_question`, `create_refining_question`, `link`, `status`, `list_nodes`, `get_node`, `search`, `zoom`, `record_fact`, `chat`, `chat_stream`, `backfill`, `seed_fixture`, `health` |
 | `client.files` | File management | `upload`, `list`, `get`, `delete` |
 | `client.keys` | API key management | `create`, `list`, `get`, `delete` |
 | `client.sharing` | Sharing & permissions | `share_project`, `share_dashboard`, `share_source`, `list_project_shares`, `list_dashboard_shares`, `revoke_project_share`, `revoke_dashboard_share`, `org_share_source` |

{querri-2.0.0 → querri-2.1.0}/README.md

@@ -244,6 +244,7 @@ See **[docs/server-sdk.md](docs/server-sdk.md#user-scoped-client-as_user)** for
 | `client.projects.chats` | Chats within projects | `create`, `list`, `get`, `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`, `get_run`, `wait_for_run`, `preview`, `chat` |
+| `client.library` | Data Library — graph + librarian agent | `create_library`, `create_collection`, `create_anchor_question`, `create_refining_question`, `link`, `status`, `list_nodes`, `get_node`, `search`, `zoom`, `record_fact`, `chat`, `chat_stream`, `backfill`, `seed_fixture`, `health` |
 | `client.files` | File management | `upload`, `list`, `get`, `delete` |
 | `client.keys` | API key management | `create`, `list`, `get`, `delete` |
 | `client.sharing` | Sharing & permissions | `share_project`, `share_dashboard`, `share_source`, `list_project_shares`, `list_dashboard_shares`, `revoke_project_share`, `revoke_dashboard_share`, `org_share_source` |

querri-2.1.0/docs/data-library.md

@@ -0,0 +1,180 @@
+# Data Library — CLI + SDK reference
+
+The Data Library is Querri's knowledge-graph + semantic-search layer over Collections, Questions, Sources, Views, KPIs, and Facts. The `querri library` CLI subcommand + `client.library` SDK resource expose the full surface.
+
+This doc is the user-facing reference. For module-level architecture see [`~/Q/Querri/server-api/querri_core/library/MODULE.md`](https://github.com/Querri-inc/server-api/blob/feat/data-overview/server-api/querri_core/library/MODULE.md) and the program-level [`documentation/data-library/`](https://github.com/Querri-inc/server-api/tree/feat/data-overview/documentation/data-library).
+
+## Auth + setup
+
+```bash
+export QUERRI_API_KEY=qk_...
+export QUERRI_ORG_ID=<tenant-id>      # required for API-key auth
+export QUERRI_HOST=http://localhost   # dev; production defaults to https://app.querri.com
+```
+
+Most commands take `--library-id` explicitly. To save typing, set an active library once and subsequent commands pick it up:
+
+```bash
+querri library use lib_<tenant-id>_<uuid>
+```
+
+The active library is stored in `~/.querri/library_context.json`. Override per-call with `--library-id` or `QUERRI_LIBRARY_ID`.
+
+## Quick start — the demo path
+
+```bash
+# 1. Create a library and select it.
+querri library create-library "Primary Library"
+querri library use <library-id-printed-above>
+
+# 2. Seed it with realistic demo data (5 collections, 16 sources, ~150 series).
+querri library seed-demo --fixture demo-acme
+
+# 3. Inspect.
+querri library status
+querri library list Collection
+querri library list ViewStub
+
+# 4. Search semantically.
+querri library search "customer churn signals"
+querri library zoom "marketing attribution by channel" --zoom 50 --explain
+
+# 5. Chat with the Librarian agent.
+querri library chat "What collections relate to revenue?" --new --show-tools
+
+# 6. Record a Fact (CLI-direct OR via the agent).
+querri library record-fact \
+  "orders.status enum gained 'awaiting_carrier' in Mar 2026" \
+  --attach <source-node-id> --kind data_quality
+
+# 7. Have the agent commission a new view.
+querri library chat \
+  "Commission a view called orders_by_country that sums total_amount grouped by shipping_country, using the orders source. Build it." \
+  --show-tools
+```
+
+## CLI reference
+
+All commands accept `--json` (a top-level flag, e.g. `querri --json library status`) for scripting.
+
+### Workspace state
+
+| Command | What it does |
+|---|---|
+| `querri library use <library-id>` | Set active library (persists across invocations). |
+| `querri library status [--library-id <id>]` | Counts per node_kind + tenant + total. |
+| `querri library health` | Tenant-scoped health probe (Mongo doc count, embedding model). |
+
+### Create
+
+| Command | What it does |
+|---|---|
+| `querri library create-library <name> [--summary <s>]` | New `Library` node. |
+| `querri library create-collection <name> [--anchor "<text>"] [--summary <s>]` | New `Collection`. With `--anchor` also mints an `AnchorQuestion` + the `anchor_of` edge in one call. |
+| `querri library create-question <text> [--refining] [--name <n>]` | Anchor question by default; pass `--refining` for a `RefiningQuestion`. |
+| `querri library add-refining <anchor-id> "<text>"` | New `RefiningQuestion` linked to the anchor via `refines`. |
+| `querri library link <a> <b> <relation> [--weight X] [--confidence X]` | Bidirectional edge between two existing nodes. `<relation>` is one of `contains`, `anchor_of`, `refines`, `parent_of`, `in_category`, `uses_source`, `uses_view`, `connector_provides`, `view_built_from`, `series_in`, `about`, `semantic_neighbor`, `mentions`. |
+
+### Read
+
+| Command | What it does |
+|---|---|
+| `querri library get <node-id>` | Fetch a single node by id. |
+| `querri library list <node-kind> [--limit N]` | All nodes of a given kind in the active library. |
+| `querri library search <query> [--kind K] [--limit N] [--surface S]` | Vector ANN search — flat top-K, no graph traversal. Fast surface. |
+| `querri library zoom <query> [--zoom N] [--budget N] [--top-k N] [--threshold X] [--kind K] [--explain]` | Vector-seeded multi-focal graph zoom: ANN-resolves focals, BFS up to 2 hops, scores by `edge.confidence × edge.weight × (zoom/100)^hops`. `--explain` prints per-stage latency + algorithm decisions. |
+| `querri library zoom --focal <id> [--focal <id>] [--zoom N]` | Skip ANN; zoom directly from given focal IDs (for iterative drill-in). |
+
+### Write — facts + view commissioning
+
+| Command | What it does |
+|---|---|
+| `querri library record-fact "<statement>" --attach <node-id> [--attach <id>] [--kind <K>] [--evidence <url>] [--confidence X]` | Create a `Fact` node + `about` edges to each `--attach` target. `--kind` is one of `contextual_note` (default), `data_quality`, `timing`, `scope_constraint`. |
+| `querri library chat "<message>" [--new] [--chat-id <id>] [--show-tools]` | Streaming chat with the LibrarianAgent. Three tools available to the agent: `search_graph`, `record_fact`, `commission_view`. `--show-tools` prints tool calls + Views-agent progress dots in real time. Active chat id persists per-library so subsequent calls continue the same conversation; `--new` starts fresh. |
+
+### Bulk / admin
+
+| Command | What it does |
+|---|---|
+| `querri library seed-demo [--fixture <name>]` | Apply a named demo fixture (currently: `demo-acme`). Writes both library_graph stubs AND real legacy `sources` + `connectors` docs so the Views agent can resolve fixture sources. Idempotent. |
+| `querri library backfill [--library-id <id>] [--no-series]` | Walk the tenant's existing `connectors` + `sources` collections and create matching stubs in `library_graph`. Idempotent. |
+
+## SDK reference
+
+Sync (`client.library`) and async (`client.library` on `AsyncQuerri`) have identical surfaces.
+
+```python
+from querri import Querri
+
+client = Querri(api_key="qk_...", org_id="<tenant>", host="http://localhost")
+
+# Workspace
+status = client.library.status(library_id="lib_...")
+print(status.counts_by_kind)            # {"Collection": 8, "Fact": 4, ...}
+
+# Search
+hits = client.library.search(query="churn risk", library_id="lib_...", limit=5)
+for h in hits.results:
+    print(h.score, h.node_kind, h.name)
+
+# Vector-seeded graph zoom
+zoom = client.library.zoom(
+    library_id="lib_...",
+    query="channel attribution and ROI",
+    zoom=50, budget_tokens=2000, top_k_focal=4,
+)
+for f in zoom.focal_nodes:
+    print(f.score, f.confidence_tier, f.node_kind, f.name)
+for n in zoom.subgraph_nodes:
+    print(n.edge_strength, n.hops, "/".join(n.edge_path), n.name)
+
+# Record a fact via the API directly
+fact = client.library.record_fact(
+    library_id="lib_...",
+    statement="orders.status enum gained 'awaiting_carrier' in Mar 2026",
+    fact_kind="data_quality",
+    source_node_ids=["src_..."],
+    evidence_refs=["https://runbooks/orders-status-evolution"],
+    confidence=0.95,
+)
+
+# Chat — drained ChatResponse
+result = client.library.chat(
+    library_id="lib_...",
+    message="What collections relate to revenue?",
+    chat_id=None,                       # omit to start fresh
+)
+print(result.assistant_message)
+print(result.tool_calls)                # list of {name, input, result, duration_ms}
+
+# Chat — streaming events (sync iterator)
+for event in client.library.chat_stream(
+    library_id="lib_...",
+    message="Commission a payment_failures view from the payments source",
+):
+    print(event["type"], event.get("name") or event.get("text", "")[:80])
+```
+
+### Streaming event types
+
+The chat stream yields these `type`s (in order, typically):
+
+| Type | Payload |
+|---|---|
+| `tool_use` | `{tool_use_id, name, input}` — emitted right before each tool call |
+| `tool_progress` | `{tool_use_id, raw}` — pass-through inner-agent SSE chunks during `commission_view` |
+| `tool_result` | `{tool_use_id, name, input, result, duration_ms}` |
+| `assistant_text` | `{text}` — terminal LLM text in the final turn |
+| `done` | `{chat_id, library_id, assistant_message, turns_used, stop_reason, input_tokens, output_tokens, total_ms}` |
+| `error` | `{message}` — stream-level failure |
+
+## Scopes
+
+Library routes require API-key scopes:
+
+| Scope | Routes |
+|---|---|
+| `admin:library:read` | GET `/library/nodes`, `/library/nodes/{id}`, `/library/status`, `/library/health`, POST `/library/search`, `/library/zoom` |
+| `admin:library:write` | POST `/library/libraries`, `/library/collections`, `/library/questions/*`, `/library/edges`, `/library/facts`, `/library/backfill`, `/library/seed-fixture`, `/library/chat` |
+
+The wildcard `*` superadmin scope satisfies both. JWT auth gives both scopes to `member` role.

{querri-2.0.0 → querri-2.1.0}/querri/_client.py

@@ -14,6 +14,7 @@ if TYPE_CHECKING:
     from .resources.embed import AsyncEmbed, Embed
     from .resources.files import AsyncFiles, Files
     from .resources.keys import AsyncKeys, Keys
+    from .resources.library import AsyncLibrary, Library
     from .resources.policies import AsyncPolicies, Policies
     from .resources.projects import AsyncProjects, Projects
     from .resources.sharing import AsyncSharing, Sharing
@@ -87,6 +88,7 @@ class Querri:
         self._sharing: object | None = None
         self._usage: object | None = None
         self._audit: object | None = None
+        self._library: object | None = None
 
     @property
     def users(self) -> "Users":
@@ -184,6 +186,14 @@ class Querri:
             self._audit = Audit(self._http)
         return self._audit  # type: ignore[return-value]
 
+    @property
+    def library(self) -> "Library":
+        if self._library is None:
+            from .resources.library import Library
+
+            self._library = Library(self._http)
+        return self._library  # type: ignore[return-value]
+
     def as_user(self, session: dict[str, Any]) -> "UserQuerri":
         """Create a user-scoped client from a ``get_session()`` result.
 
@@ -270,6 +280,7 @@ class AsyncQuerri:
         self._sharing: object | None = None
         self._usage: object | None = None
         self._audit: object | None = None
+        self._library: object | None = None
 
     @property
     def users(self) -> "AsyncUsers":
@@ -367,6 +378,14 @@ class AsyncQuerri:
             self._audit = AsyncAudit(self._http)
         return self._audit  # type: ignore[return-value]
 
+    @property
+    def library(self) -> "AsyncLibrary":
+        if self._library is None:
+            from .resources.library import AsyncLibrary
+
+            self._library = AsyncLibrary(self._http)
+        return self._library  # type: ignore[return-value]
+
     def as_user(self, session: dict[str, Any]) -> "AsyncUserQuerri":
         """Create a user-scoped async client from a ``get_session()`` result.
 

{querri-2.0.0 → querri-2.1.0}/querri/_exceptions.py

@@ -163,16 +163,35 @@ def raise_for_status(
         retry_after: Retry-After value from response headers.
     """
     error = body.get("error", {})
-    if isinstance(error, dict):
+    if isinstance(error, dict) and error:
         err_type = str(error.get("type", ""))
         err_code = str(error.get("code", ""))
         err_message = str(error.get("message", f"HTTP {status}"))
         err_doc_url = error.get("doc_url")
     else:
+        # FastAPI's `HTTPException(detail=...)` produces `{"detail": ...}`
+        # with no `error` envelope. Prefer the `detail` payload over a
+        # generic "HTTP {status}" so admin-gate / validation errors carry
+        # the helpful server-side message through to the CLI user.
+        # `detail` may be a string OR a nested dict (FastAPI lets you raise
+        # an HTTPException with a structured detail).
+        detail = body.get("detail")
         err_type = ""
         err_code = ""
-        err_message = str(body) if body else f"HTTP {status}"
         err_doc_url = None
+        if isinstance(detail, str) and detail:
+            err_message = detail
+        elif isinstance(detail, dict) and detail:
+            nested_error = detail.get("error")
+            if isinstance(nested_error, dict) and nested_error:
+                err_type = str(nested_error.get("type", ""))
+                err_code = str(nested_error.get("code", ""))
+                err_message = str(nested_error.get("message", f"HTTP {status}"))
+                err_doc_url = nested_error.get("doc_url")
+            else:
+                err_message = str(detail)
+        else:
+            err_message = str(body) if body else f"HTTP {status}"
 
     exc_class = _STATUS_MAP.get(status, APIError)
 

querri-2.1.0/querri/_version.py

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

{querri-2.0.0 → querri-2.1.0}/querri/cli/_app.py

@@ -14,6 +14,7 @@ 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.library import library_app
 from querri.cli.policies import policies_app
 from querri.cli.projects import projects_app
 from querri.cli.sharing import sharing_app
@@ -227,6 +228,11 @@ main_app.add_typer(
     name="dashboard",
     rich_help_panel="[#f15a24]Projects & Data[/#f15a24]",
 )
+main_app.add_typer(
+    library_app,
+    name="library",
+    rich_help_panel="[#f15a24]Projects & Data[/#f15a24]",
+)
 
 # ── Administration ──────────────────────────────────────────────────────
 main_app.add_typer(