Metadata-Version: 2.4
Name: record-assessment-backend
Version: 2.0.1
Summary: Backend SDK for SmartAI Assessment Portal — create sessions and manage assessments from your server.
License: MIT
License-File: LICENSE
Keywords: assessment,backend,sdk,smartai
Requires-Python: >=3.8
Requires-Dist: httpx>=0.24.0
Description-Content-Type: text/markdown

# record-assessment-backend

Backend SDK for SmartAI Assessment Portal — create sessions and manage assessments from your server.

## Install

```bash
pip install record-assessment-backend
```

## Usage

```python
from record_assessment_backend import AssessmentClient

client = AssessmentClient(
    api_key="VFN_LIVE_...",
    secret_key="VFN_SK_LIVE_...",
    base_url="https://your-api.com/api/v1",           # optional
    webhook_base_url="https://your-webhook-api.com",   # optional
    timeout=60.0,                                       # optional — create_campaign calls OpenAI server-side
)
```

### Create a session

```python
result = client.create_session(
    candidate_id="mongo_candidate_id",
    name="Jane Doe",
    email="jane@example.com",
)
token = result["token"]
```

### Create a campaign

Generates the assessment immediately. `method` must be `"programming"` or
`"knowledge"` and the workflow must have that verification method enabled —
`"programming"` generates a programming-only assessment, `"knowledge"`
generates a mix of mcq/true-false/short-answer/long-answer per the workflow's
configured counts. `workflow_id`, `method`, and `name`+`email` are required —
everything else falls back to the workflow's own defaults:

```python
campaign = client.create_campaign(
    workflow_id="wf_...",
    method="knowledge",
    name="Jane Doe",
    email="jane@example.com",
    job_title="Backend Engineer",  # optional
    experience="3",                 # optional
    level="2-5",                    # optional
)
assessment_link = campaign["assessmentLink"]
```

### List assessments

```python
assessments = client.list_assessments()
```

### Poll for results

Fired by record-assessment-backend when a candidate submits or is
disqualified — event types `assessment.completed` / `assessment.disqualified`:

```python
result = client.get_webhook_events()
for event in result["events"]:
    print(event["event"], event["assessmentId"], event.get("score"))
if result["events"]:
    client.acknowledge_webhook_events([e["eventId"] for e in result["events"]])
```

## Headers sent on every request

```
x-api-key:   VFN_LIVE_...
x-signature: hmac-sha256(secret_key, "METHOD:/api/v1/path:timestamp:sorted_body")
x-timestamp: 1234567890123
```

## Notes

- `secret_key` is HMAC-sign-only for signed requests (`list_assessments`);
  `create_session` and `create_campaign` send it directly as `x-secret-key`
  instead, since those endpoints authenticate with `x-api-key` +
  `x-secret-key` rather than a signature.
- There's a single deployed backend for this integration — no separate
  test/live URLs. `base_url` and `webhook_base_url` both default to it, and
  can each be overridden independently via the constructor params (e.g. for
  local testing). Webhook events do use a different response envelope
  though: `{status, code, data}` on success, `{status, code, message}` on
  error — not `{success, data}` like the rest of this client.

## License

MIT
