zeriq-team 0.1.0__tar.gz

zeriq_team-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+.venv/
+dist/
+__pycache__/

zeriq_team-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 — first published release
+
+First release: knowledge (documents, upsert, search), personas and ask, conversations, rooms
+(create with AI teammates and people, messages, end, summarize, reports), action items and
+meeting reads. Retries, idempotency keys, typed errors, pagination, `wait_until_ready`,
+`wait_for_replies` and `wait_for_report`; sync and async clients.
+
+Room streams: `rooms.stream` (server-sent events: `persona.thinking`, `message.created`, `run.completed`, `run.failed`), resuming with Last-Event-ID; `messages.send` returns the reply `run_id`.
+
+Webhooks: endpoints (create, update, rotate secret, test, delete), the deliveries log and redelivery, and signature verification (`zeriq_team.webhooks.verify`).

zeriq_team-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.5
+Name: zeriq-team
+Version: 0.1.0
+Summary: Official Python SDK for the Zeriq Teams API
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.24
+Requires-Dist: typing-extensions>=4.7
+Provides-Extra: dev
+Requires-Dist: black==24.10.0; extra == 'dev'
+Requires-Dist: datamodel-code-generator==0.26.5; extra == 'dev'
+Requires-Dist: isort==5.13.2; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# zeriq-team
+
+The official Python SDK for the [Zeriq Teams API](../../docs/developers/README.md): your AI teammates' knowledge, answers, rooms, action items and meetings, from your own systems.
+
+- Python 3.9+, sync and async clients, built on `httpx`.
+- Results are plain dicts, typed with `TypedDict`s generated from the API's OpenAPI spec (`zeriq_team.types`).
+- Retries 429, 5xx and network errors with backoff, and honours `Retry-After`. Every POST gets an `Idempotency-Key`, so retries never create anything twice.
+
+```bash
+pip install zeriq-team
+```
+
+## Quick start
+
+```python
+from zeriq_team import Zeriq
+
+zq = Zeriq()  # reads ZERIQ_TEAM_API_KEY (and ZERIQ_TEAM_BASE_URL)
+
+# Knowledge: upsert by your own id, then search (no AI model, no credits)
+zq.knowledge.documents.upsert(external_id="wiki:refunds", title="Refunds", text="…")
+hits = zq.knowledge.search(query="refund policy", top_k=5)["data"]
+
+# Ask an AI teammate (no tools unless you allow them)
+answer = zq.personas.ask("prs_…", input="Draft a reply to this customer: …")
+print(answer["answer"], answer["usage"])
+
+# Rooms: create, post, stream the replies as they arrive, end
+room = zq.rooms.create(title="Pricing review", personas=["prs_…"])
+sent = zq.rooms.messages.send(room["id"], content="Should we add annual plans?")
+for event in zq.rooms.stream(room["id"], run_id=sent["run_id"]):  # ends with the run
+    if event["event"] == "message.created":
+        print(event["data"]["message"]["content"])
+zq.rooms.end(room["id"])
+
+# Lists return the first page; iterate to walk every page
+for item in zq.action_items.list(status="open"):
+    zq.action_items.update(item["id"], external_ref="https://linear.app/…")
+```
+
+Async is the same API, awaited:
+
+```python
+from zeriq_team import AsyncZeriq
+
+async with AsyncZeriq() as zq:
+    answer = await zq.personas.ask("prs_…", input="…")
+    async for item in zq.action_items.list(status="open"):
+        ...
+```
+
+For QA, set `base_url="https://api.qa.zeriq.app"`.
+
+## Webhooks
+
+```python
+endpoint = zq.webhooks.endpoints.create(url="https://example.com/zeriq", event_types=["action_item.created"])
+secret = endpoint["secret"]  # shown only now
+
+# In your handler, with the raw request body:
+from zeriq_team import webhooks, WebhookVerificationError
+
+event = webhooks.verify(raw_body, headers["Zeriq-Signature"], secret)
+if event["type"] == "action_item.created":
+    ...
+```
+
+## Errors
+
+Every API error is an `APIError` with `status`, `code`, `param` and `request_id`. Subclasses:
+`InvalidRequestError` (400), `AuthenticationError` (401), `CreditsExhaustedError` (402 — retry with
+`allow_downgrade=True`), `PlanLimitError` (402), `InsufficientScopeError` (403, `param` is the
+missing scope), `ToolNotPermittedError` (403), `NotFoundError` (404, also for other workspaces'
+objects), `RateLimitError` (429 after retries), plus `APIConnectionError` / `APITimeoutError`.
+Results carry the ID too: `answer.request_id`.
+
+## Options
+
+```python
+Zeriq(api_key=..., base_url=..., timeout=60.0, max_retries=2, http_client=httpx.Client(...))
+zq.rooms.create(title="x", idempotency_key="my-key")
+```
+
+## Examples
+
+[`examples/`](examples): a knowledge-base sync, an async room bot, and action items → Linear.
+
+```bash
+ZERIQ_TEAM_API_KEY=zqt_sk_… python examples/kb_sync.py
+```
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e '.[dev]'
+scripts/generate.sh      # types from ../team-api-spec/openapi.json
+.venv/bin/python -m pytest
+```
+
+The contract tests that run this SDK against the real API app live in
+`services/team-agent/tests/test_sdk_contract.py`.

zeriq_team-0.1.0/README.md

@@ -0,0 +1,101 @@
+# zeriq-team
+
+The official Python SDK for the [Zeriq Teams API](../../docs/developers/README.md): your AI teammates' knowledge, answers, rooms, action items and meetings, from your own systems.
+
+- Python 3.9+, sync and async clients, built on `httpx`.
+- Results are plain dicts, typed with `TypedDict`s generated from the API's OpenAPI spec (`zeriq_team.types`).
+- Retries 429, 5xx and network errors with backoff, and honours `Retry-After`. Every POST gets an `Idempotency-Key`, so retries never create anything twice.
+
+```bash
+pip install zeriq-team
+```
+
+## Quick start
+
+```python
+from zeriq_team import Zeriq
+
+zq = Zeriq()  # reads ZERIQ_TEAM_API_KEY (and ZERIQ_TEAM_BASE_URL)
+
+# Knowledge: upsert by your own id, then search (no AI model, no credits)
+zq.knowledge.documents.upsert(external_id="wiki:refunds", title="Refunds", text="…")
+hits = zq.knowledge.search(query="refund policy", top_k=5)["data"]
+
+# Ask an AI teammate (no tools unless you allow them)
+answer = zq.personas.ask("prs_…", input="Draft a reply to this customer: …")
+print(answer["answer"], answer["usage"])
+
+# Rooms: create, post, stream the replies as they arrive, end
+room = zq.rooms.create(title="Pricing review", personas=["prs_…"])
+sent = zq.rooms.messages.send(room["id"], content="Should we add annual plans?")
+for event in zq.rooms.stream(room["id"], run_id=sent["run_id"]):  # ends with the run
+    if event["event"] == "message.created":
+        print(event["data"]["message"]["content"])
+zq.rooms.end(room["id"])
+
+# Lists return the first page; iterate to walk every page
+for item in zq.action_items.list(status="open"):
+    zq.action_items.update(item["id"], external_ref="https://linear.app/…")
+```
+
+Async is the same API, awaited:
+
+```python
+from zeriq_team import AsyncZeriq
+
+async with AsyncZeriq() as zq:
+    answer = await zq.personas.ask("prs_…", input="…")
+    async for item in zq.action_items.list(status="open"):
+        ...
+```
+
+For QA, set `base_url="https://api.qa.zeriq.app"`.
+
+## Webhooks
+
+```python
+endpoint = zq.webhooks.endpoints.create(url="https://example.com/zeriq", event_types=["action_item.created"])
+secret = endpoint["secret"]  # shown only now
+
+# In your handler, with the raw request body:
+from zeriq_team import webhooks, WebhookVerificationError
+
+event = webhooks.verify(raw_body, headers["Zeriq-Signature"], secret)
+if event["type"] == "action_item.created":
+    ...
+```
+
+## Errors
+
+Every API error is an `APIError` with `status`, `code`, `param` and `request_id`. Subclasses:
+`InvalidRequestError` (400), `AuthenticationError` (401), `CreditsExhaustedError` (402 — retry with
+`allow_downgrade=True`), `PlanLimitError` (402), `InsufficientScopeError` (403, `param` is the
+missing scope), `ToolNotPermittedError` (403), `NotFoundError` (404, also for other workspaces'
+objects), `RateLimitError` (429 after retries), plus `APIConnectionError` / `APITimeoutError`.
+Results carry the ID too: `answer.request_id`.
+
+## Options
+
+```python
+Zeriq(api_key=..., base_url=..., timeout=60.0, max_retries=2, http_client=httpx.Client(...))
+zq.rooms.create(title="x", idempotency_key="my-key")
+```
+
+## Examples
+
+[`examples/`](examples): a knowledge-base sync, an async room bot, and action items → Linear.
+
+```bash
+ZERIQ_TEAM_API_KEY=zqt_sk_… python examples/kb_sync.py
+```
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e '.[dev]'
+scripts/generate.sh      # types from ../team-api-spec/openapi.json
+.venv/bin/python -m pytest
+```
+
+The contract tests that run this SDK against the real API app live in
+`services/team-agent/tests/test_sdk_contract.py`.

zeriq_team-0.1.0/examples/action_items_to_linear.py

@@ -0,0 +1,43 @@
+"""Mirror open action items into Linear and link them back with ``external_ref``.
+Without LINEAR_API_KEY it's a dry run that only lists what it would create.
+
+    ZERIQ_TEAM_API_KEY=zqt_sk_… [LINEAR_API_KEY=… LINEAR_TEAM_ID=…] python examples/action_items_to_linear.py
+Scopes: tasks:read, tasks:write (plus rooms:read:all to see rooms the key didn't create)
+"""
+
+import os
+from datetime import datetime, timedelta, timezone
+
+import httpx
+
+from zeriq_team import Zeriq
+
+zq = Zeriq()
+linear_key = os.environ.get("LINEAR_API_KEY")
+
+
+def create_linear_issue(title: str, description: str) -> str:
+    resp = httpx.post(
+        "https://api.linear.app/graphql",
+        headers={"Authorization": linear_key or ""},
+        json={"query": "mutation($input: IssueCreateInput!) { issueCreate(input: $input) { issue { url } } }",
+              "variables": {"input": {"teamId": os.environ.get("LINEAR_TEAM_ID"), "title": title, "description": description}}},
+    ).json()
+    url = (((resp.get("data") or {}).get("issueCreate") or {}).get("issue") or {}).get("url")
+    if not url:
+        raise RuntimeError(f"Linear: {resp.get('errors')}")
+    return url
+
+
+count = 0
+for item in zq.action_items.list(status="open", since=datetime.now(timezone.utc) - timedelta(days=7)):
+    if item.get("external_ref"):
+        continue  # already tracked somewhere
+    count += 1
+    if not linear_key:
+        print(f"[dry run] would create: {item['title']} ({item.get('assignee') or 'unassigned'})")
+        continue
+    url = create_linear_issue(item["title"], f"From Zeriq room {item['room_id']}")
+    zq.action_items.update(item["id"], external_ref=url)
+    print(f"{item['title']} → {url}")
+print(f"{count} open action item(s) without a link in the last 7 days")

zeriq_team-0.1.0/examples/kb/onboarding.md

@@ -0,0 +1,4 @@
+# Onboarding checklist (SDK example)
+
+New teammates get a laptop on day one, meet their buddy on day two,
+and ship a small change to production by the end of week one.

zeriq_team-0.1.0/examples/kb/refunds.md

@@ -0,0 +1,5 @@
+# Refund policy (SDK example)
+
+Customers on annual plans can request a full refund within 30 days of purchase.
+Monthly plans are not refunded, but can be cancelled at any time.
+Refunds reach the original payment method within 5 business days.

zeriq_team-0.1.0/examples/kb_sync.py

@@ -0,0 +1,23 @@
+"""Keep your docs in Zeriq's knowledge base: upsert each file by its own id, wait until it's
+searchable, then search. Safe to re-run.
+
+    ZERIQ_TEAM_API_KEY=zqt_sk_… python examples/kb_sync.py
+Scopes: knowledge:read, knowledge:write
+"""
+
+from pathlib import Path
+
+from zeriq_team import Zeriq
+
+zq = Zeriq()
+for path in sorted((Path(__file__).parent / "kb").glob("*.md")):
+    text = path.read_text()
+    title = text.splitlines()[0].lstrip("# ").strip()
+    doc = zq.knowledge.documents.upsert(external_id=f"sdk-example:kb:{path.name}", title=title, text=text)
+    ready = zq.knowledge.documents.wait_until_ready(doc["id"])
+    print(f"synced {path.name} → {ready['id']} ({ready['status']}, {ready['chunk_count']} chunks)")
+
+hits = zq.knowledge.search(query="How long do refunds take?", top_k=3)["data"]
+for hit in hits:
+    print(f"{hit['score']:.2f}  {hit['title']}: {hit['content'][:80]}…")
+assert any(h["title"].startswith("Refund policy") for h in hits), "Expected the refund policy in the results"

zeriq_team-0.1.0/examples/room_bot.py

@@ -0,0 +1,25 @@
+"""Run a room from your own system: create it with an AI teammate, post a question, wait for
+the replies, then end it. Uses the async client.
+
+    ZERIQ_TEAM_API_KEY=zqt_sk_… python examples/room_bot.py
+Scopes: personas:read, rooms:read, rooms:write
+"""
+
+import asyncio
+import os
+
+from zeriq_team import AsyncZeriq
+
+
+async def main() -> None:
+    async with AsyncZeriq() as zq:
+        persona_id = os.environ.get("ZERIQ_EXAMPLE_PERSONA") or (await zq.personas.list())["data"][0]["id"]
+        room = await zq.rooms.create(title="[SDK example] Launch check", personas=[persona_id])
+        print(f"room {room['id']} with {', '.join(p['name'] for p in room['personas'])}")
+        sent = await zq.rooms.messages.send(room["id"], content="In two sentences: what should a launch checklist cover?")
+        for m in await zq.rooms.wait_for_replies(room["id"], sent["id"]):
+            print(f"{m['sender']['name']}: {m['content']}")
+        print("ended:", (await zq.rooms.end(room["id"], outcome="success"))["status"])
+
+
+asyncio.run(main())

zeriq_team-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "zeriq-team"
+version = "0.1.0"
+description = "Official Python SDK for the Zeriq Teams API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+dependencies = ["httpx>=0.24,<1", "typing_extensions>=4.7"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "datamodel-code-generator==0.26.5", "black==24.10.0", "isort==5.13.2"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zeriq_team"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["req(id): plan task this test covers"]

zeriq_team-0.1.0/scripts/generate.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env sh
+# Regenerates src/zeriq_team/types.py (TypedDicts) from the committed OpenAPI spec.
+set -e
+cd "$(dirname "$0")/.."
+datamodel-codegen --input ../team-api-spec/openapi.json --input-file-type openapi \
+  --output-model-type typing.TypedDict --target-python-version 3.9 \
+  --use-schema-description --use-field-description --disable-timestamp \
+  --enum-field-as-literal all --use-standard-collections --use-union-operator \
+  --output src/zeriq_team/types.py

zeriq_team-0.1.0/src/zeriq_team/__init__.py

@@ -0,0 +1,36 @@
+"""Zeriq Teams API — official Python SDK.
+
+    from zeriq_team import Zeriq
+
+    zq = Zeriq()  # reads ZERIQ_TEAM_API_KEY
+    answer = zq.personas.ask("prs_…", input="What changed in our refund policy?")
+"""
+
+from ._client import AsyncZeriq, Zeriq
+from ._core import AsyncPager, Page, SyncPage, ZeriqObject
+from ._errors import (
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    ConflictError,
+    CreditsExhaustedError,
+    InsufficientScopeError,
+    InternalServerError,
+    InvalidRequestError,
+    NotFoundError,
+    PermissionDeniedError,
+    PlanLimitError,
+    RateLimitError,
+    ToolNotPermittedError,
+    ZeriqError,
+)
+from ._version import __version__
+from .webhooks import WebhookVerificationError
+
+__all__ = [
+    "APIConnectionError", "APIError", "APITimeoutError", "AsyncPager", "AsyncZeriq", "AuthenticationError",
+    "ConflictError", "CreditsExhaustedError", "InsufficientScopeError", "InternalServerError", "InvalidRequestError",
+    "NotFoundError", "Page", "PermissionDeniedError", "PlanLimitError", "RateLimitError", "SyncPage",
+    "ToolNotPermittedError", "WebhookVerificationError", "Zeriq", "ZeriqError", "ZeriqObject", "__version__",
+]

zeriq_team-0.1.0/src/zeriq_team/_client.py

@@ -0,0 +1,116 @@
+"""The sync (``Zeriq``) and async (``AsyncZeriq``) clients."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Mapping, Optional
+
+import httpx
+
+from ._core import DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, AsyncCore, SyncCore
+from ._resources import (
+    ActionItems,
+    AsyncBots,
+    AsyncDocuments,
+    AsyncRooms,
+    Bots,
+    Conversations,
+    Documents,
+    Knowledge,
+    Meetings,
+    Personas,
+    RoomMessages,
+    Rooms,
+    Webhooks,
+)
+
+if TYPE_CHECKING:
+    from .types import Me
+
+
+class Zeriq:
+    """Zeriq Teams API client.
+
+    >>> zq = Zeriq()  # reads ZERIQ_TEAM_API_KEY
+    >>> zq.personas.ask("prs_…", input="What changed in our refund policy?")["answer"]
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Optional[Mapping[str, str]] = None,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        self._core = SyncCore(api_key=api_key, base_url=base_url, timeout=timeout, max_retries=max_retries,
+                              default_headers=default_headers, http_client=http_client)
+        self.knowledge = Knowledge(self._core, Documents(self._core))
+        self.personas = Personas(self._core)
+        self.conversations = Conversations(self._core)
+        self.rooms = Rooms(self._core, RoomMessages(self._core))
+        self.action_items = ActionItems(self._core)
+        self.meetings = Meetings(Bots(self._core))
+        self.webhooks = Webhooks(self._core)
+
+    def me(self) -> "Me":
+        """The workspace, key, scopes and tool access behind this API key."""
+        return self._core.request("GET", "/v1/me")  # type: ignore[no-any-return]
+
+    def request(self, method: str, path: str, **kwargs: Any) -> Any:
+        """Low-level access for endpoints the SDK doesn't wrap yet."""
+        return self._core.request(method, path, **kwargs)
+
+    def close(self) -> None:
+        self._core.close()
+
+    def __enter__(self) -> "Zeriq":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+class AsyncZeriq:
+    """Async Zeriq Teams API client: the same API, awaited.
+
+    >>> async with AsyncZeriq() as zq:
+    ...     async for item in zq.action_items.list(status="open"):
+    ...         print(item["title"])
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Optional[Mapping[str, str]] = None,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        self._core = AsyncCore(api_key=api_key, base_url=base_url, timeout=timeout, max_retries=max_retries,
+                               default_headers=default_headers, http_client=http_client)
+        self.knowledge = Knowledge(self._core, AsyncDocuments(self._core))
+        self.personas = Personas(self._core)
+        self.conversations = Conversations(self._core)
+        self.rooms = AsyncRooms(self._core, RoomMessages(self._core))
+        self.action_items = ActionItems(self._core)
+        self.meetings = Meetings(AsyncBots(self._core))
+        self.webhooks = Webhooks(self._core)
+
+    async def me(self) -> "Me":
+        return await self._core.request("GET", "/v1/me")  # type: ignore[no-any-return]
+
+    async def request(self, method: str, path: str, **kwargs: Any) -> Any:
+        return await self._core.request(method, path, **kwargs)
+
+    async def close(self) -> None:
+        await self._core.close()
+
+    async def __aenter__(self) -> "AsyncZeriq":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()