Metadata-Version: 2.4
Name: palqee-prisma-client
Version: 0.4.0
Summary: Prisma AI platform client for evaluations, 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

# palqee-prisma-client

Python client for the Prisma AI platform. Provides async access to projects, runs, analytics, and evaluations through a typed API.

## Prerequisites

- Python 3.10 or later
- A Prisma AI API key

## Installation

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

## Quick start

```python
from palqee_prisma_client import PrismaClient

async with PrismaClient(
    api_key="pq_prisma_sk_...",
    workspace_id="<workspace-uuid>",
    base_url="https://your-prisma-host",
) as client:
    # Create a project and a run
    project = await client.projects.get_or_create("my-app")
    run = await client.runs.create(project.id)
```

## Projects

```python
# List all projects in the workspace
page = await client.projects.list()
for project in page.items:
    print(project.id, project.name)

# Get a single project
project = await client.projects.get(project_id)

# Update a project
project = await client.projects.update(project_id, name="new-name", description="...")

# Get aggregate stats
stats = await client.projects.stats(project_id)
print(stats.total_runs, stats.total_traces)

# Delete a project
await client.projects.delete(project_id)
```

## Runs

```python
# List runs in a project (with optional filters)
page = await client.runs.list(project_id, status="completed", limit=50)
for run in page.items:
    print(run.id, run.status)

# Get a single run
run = await client.runs.get(run_id)

# Update a run
run = await client.runs.update(run_id, status="completed")

# Get stats and evaluation metrics
stats = await client.runs.stats(run_id)
metrics = await client.runs.metrics(run_id)
print(metrics.metrics)  # {"correctness": 0.88, ...}

# Delete a run
await client.runs.delete(run_id)
```

## Analytics

```python
# Structured query
result = await client.analytics.query(
    dimensions=["model_name"],
    measures=["trace_count", "avg_latency_ms"],
    filters=[{"field": "project_id", "op": "eq", "value": project_id}],
)
for row in result.rows:
    print(row.dimensions, row.measures)

# Project overview
overview = await client.analytics.overview(project_id, period="7d")
print(overview.total_traces, overview.total_cost_usd)

# Cost breakdown
costs = await client.analytics.costs(project_id, period="30d")
for item in costs.breakdown:
    print(item.label, item.cost_usd)

# Export data
export = await client.analytics.export("csv", project_id=project_id)
print(export.download_url)
```

## Evaluations

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

# Get evaluation summary for a project
summary = await client.evaluations.summary(project_id, period="7d")
print(summary.avg_score, summary.scores_by_evaluator)

# List evaluators configured for a project
evaluators = await client.evaluations.evaluators(project_id)
for ev in evaluators:
    print(ev.type, ev.name)
```

## Pagination

List methods return a `Page[T]` object:

```python
page = await client.projects.list(limit=20, offset=0)
print(page.total, page.has_more)
projects = page.items  # list[Project]
```

## Configuration

| Parameter | Environment variable | Description |
|-----------|---------------------|-------------|
| `api_key` | `PALQEE_PRISMA_API_KEY` | API key (`pq_prisma_sk_...`) |
| `workspace_id` | `PALQEE_PRISMA_WORKSPACE_ID` | Workspace UUID |
| `base_url` | `PALQEE_PRISMA_BASE_URL` | API gateway base URL |
| `timeout` | — | Request timeout in seconds (default 30) |
| `max_retries` | — | Max retries for transient errors (default 2) |

## Error handling

All exceptions inherit from `PrismaError`:

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

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

| Exception | HTTP status | Description |
|-----------|-------------|-------------|
| `PrismaAuthenticationError` | — | Invalid or missing API key (client-side) |
| `PrismaAuthorizationError` | 401, 403 | Server rejected the 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 |

## Version

```python
from palqee_prisma_client import __version__
```

## License

MIT
