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`.
