Metadata-Version: 2.4
Name: palqee-prisma-client
Version: 0.4.1
Summary: Prisma AI platform client for validations, datasets, and jobs
Author-email: Hartley Jean-Aime <hartley@palqee.com>
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://cdn.jsdelivr.net/gh/Palqee/prisma-brand-assets@v1/prisma/palqee_prisma_client_banner_dark.png">
    <img width="2560" height="640" src="https://cdn.jsdelivr.net/gh/Palqee/prisma-brand-assets@v1/prisma/palqee_prisma_client_banner_light.png" alt="Palqee Prisma Client" />
  </picture>

  <p>Typed async Python client for the <a href="https://www.palqee.com/">Palqee Prisma</a> oversight intelligence platform.</p>

  <p>
    <a href="https://pypi.org/project/palqee-prisma-client/"><img src="https://img.shields.io/pypi/v/palqee-prisma-client.svg" alt="PyPI version" /></a>
    <a href="https://pypi.org/project/palqee-prisma-client/"><img src="https://img.shields.io/pypi/pyversions/palqee-prisma-client.svg" alt="Python versions" /></a>
    <a href="https://pypi.org/project/palqee-prisma-client/"><img src="https://img.shields.io/pypi/l/palqee-prisma-client.svg" alt="License" /></a>
    <a href="https://docs.palqee.com/docs/overview"><img src="https://img.shields.io/badge/docs-palqee.com-blue.svg" alt="Documentation" /></a>
  </p>
</div>

---

## What is this?

`palqee-prisma-client` is the **low-level HTTP client** for Palqee Prisma — the oversight intelligence platform that replaces manual review with automated, regulatory-grade validation across human and AI workflows. Use it to drive Prisma resources directly from Python: projects, runs, datasets, jobs, analytics, and validations.

Most applications should reach for [`palqee-prisma-ai`](https://pypi.org/project/palqee-prisma-ai/) — the high-level SDK that wires OpenTelemetry and validators into your stack with one call. Pick `palqee-prisma-client` when you need:

- **Direct platform control** — backfill historical data, orchestrate batch validation jobs, build admin tooling.
- **Custom integrations** — power BI dashboards, custom UIs, internal compliance tools, or CLI utilities.
- **Async-first ergonomics** — `httpx`-based, fully typed via Pydantic, designed for high-throughput pipelines.

## Installation

```bash
pip install palqee-prisma-client
```

Imports as `palqee_prisma_client`:

```python
from palqee_prisma_client import PrismaClient
```

Requires Python 3.10+.

## Quickstart

```python
import asyncio
import os
from palqee_prisma_client import PrismaClient

async def main():
    async with PrismaClient(
        api_key=os.environ["PALQEE_PRISMA_API_KEY"],
        workspace_id=os.environ["PALQEE_PRISMA_WORKSPACE_ID"],
        base_url=os.environ["PALQEE_PRISMA_BASE_URL"],
    ) as client:
        project = await client.projects.get_or_create("complaints-review")
        run = await client.runs.create(project.id)
        print(f"Created run {run.id} under project {project.id}")

asyncio.run(main())
```

With env vars set, the constructor collapses to `PrismaClient()`.

## Resources

The client exposes one resource per Prisma domain object. Every method is async and returns a typed Pydantic model.

### Projects

```python
projects = await client.projects.list()                       # Page[Project]
project  = await client.projects.get(project_id)
project  = await client.projects.update(project_id, name="new-name")
stats    = await client.projects.stats(project_id)            # total_runs, total_traces, ...
await client.projects.delete(project_id)
```

### Runs

```python
runs    = await client.runs.list(project_id, status="completed", limit=50)
run     = await client.runs.get(run_id)
run     = await client.runs.update(run_id, status="completed")
metrics = await client.runs.metrics(run_id)                   # validator scores per run
await client.runs.delete(run_id)
```

### Datasets

```python
datasets = await client.datasets.list(project_id)
dataset  = await client.datasets.create(project_id, name="golden-set", items=[...])
items    = await client.datasets.items(dataset.id)
```

### Jobs

```python
job   = await client.jobs.create(project_id, dataset_id=dataset.id, validators=["correctness"])
job   = await client.jobs.get(job.id)
jobs  = await client.jobs.list(project_id, status="running")
```

### Validations

```python
# Trigger validators on a run
result = await client.evaluations.run(run_id, evaluators=["correctness", "hallucination"])
print(result.status, result.total_evaluated)

# Project-wide validation summary
summary = await client.evaluations.summary(project_id, period="7d")
print(summary.avg_score, summary.scores_by_evaluator)

# List validators configured for a project
validators = await client.evaluations.evaluators(project_id)
```

> **Note:** the API surface uses `client.evaluations.*` for backwards compatibility. The platform now describes this domain as **validations** — both terms refer to the same resource.

### Analytics

```python
result = await client.analytics.query(
    dimensions=["model_name"],
    measures=["trace_count", "avg_latency_ms"],
    filters=[{"field": "project_id", "op": "eq", "value": project_id}],
)
overview = await client.analytics.overview(project_id, period="7d")
costs    = await client.analytics.costs(project_id, period="30d")
export   = await client.analytics.export("csv", project_id=project_id)
```

## Pagination

List endpoints return a `Page[T]`:

```python
page = await client.projects.list(limit=20, offset=0)
print(page.total, page.has_more)
for project in page.items:
    ...
```

## Configuration

| Parameter | Environment variable | Description |
|-----------|---------------------|-------------|
| `api_key` | `PALQEE_PRISMA_API_KEY` | Prisma API key (`pq_prisma_sk_...`) |
| `workspace_id` | `PALQEE_PRISMA_WORKSPACE_ID` | Workspace UUID |
| `base_url` | `PALQEE_PRISMA_BASE_URL` | Base URL of your Prisma deployment |
| `timeout` | — | Request timeout in seconds (default `30`) |
| `max_retries` | — | Retries for transient errors (default `2`) |

Full reference: [docs.palqee.com/docs/overview](https://docs.palqee.com/docs/overview).

## Error handling

All exceptions inherit from `PrismaError`. Catch the specific class you care about, fall through to the parent:

```python
from palqee_prisma_client import PrismaNotFoundError, PrismaAPIError, PrismaError

try:
    project = await client.projects.get(project_id)
except PrismaNotFoundError:
    ...
except PrismaAPIError as e:
    print(f"API error {e.status_code}: {e.message}")
except PrismaError:
    ...
```

| Exception | HTTP status | Meaning |
|-----------|-------------|---------|
| `PrismaAuthenticationError` | — | Invalid or missing API key (client-side) |
| `PrismaAuthorizationError` | 401, 403 | Server rejected credentials |
| `PrismaNotFoundError` | 404 | Resource does not exist |
| `PrismaConflictError` | 409 | Conflict with existing state |
| `PrismaUnprocessableEntityError` | 422 | Server-side validation failure |
| `PrismaAPIError` | other | Any other HTTP error |
| `PrismaTimeoutError` | — | Request timed out |
| `PrismaNetworkError` | — | Connection or transport failure |
| `PrismaValidationError` | — | Client-side input validation failure |

## When to use this vs `palqee-prisma-ai`

| Need | Reach for |
|------|-----------|
| Instrument an app once, ship traces and run validators | [`palqee-prisma-ai`](https://pypi.org/project/palqee-prisma-ai/) |
| Drive Prisma resources directly (projects, runs, jobs, datasets) | `palqee-prisma-client` (this package) |
| Both | Install both — the SDK uses this client under the hood |

## Links

- **Documentation:** [docs.palqee.com/docs/overview](https://docs.palqee.com/docs/overview)
- **High-level SDK:** [`palqee-prisma-ai`](https://pypi.org/project/palqee-prisma-ai/)
- **Tracing wrapper:** [`palqee-prisma-otel`](https://pypi.org/project/palqee-prisma-otel/)
- **Website:** [palqee.com](https://www.palqee.com/)
- **Support:** [support@palqee.com](mailto:support@palqee.com)

## License

[MIT](./LICENSE) © Palqee
