Metadata-Version: 2.4
Name: record-assessment-backend
Version: 2.0.3
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 assessment links

Fired by `create_campaign` — send these to your candidates:

```python
links = client.get_assessment_links()
for event in links["events"]:
    print("send to candidates:", event["assessmentLink"])
if links["events"]:
    client.acknowledge_assessment_links([e["eventId"] for e in links["events"]])
```

### Poll for assessment results

Fired once a candidate submits or is disqualified. Carries `score`, `passed`,
`totalMarks`, `passMarks`, `candidateName`, `candidateEmail`, `submittedAt`,
`durationMinutes`, `questionAnswers`, `proctoring`, `recording`,
`aiFeedback` — plus `reportUrl`, the shareable link to the candidate's full
result report page:

```python
results = client.get_assessment_results()
for event in results["events"]:
    print(event["candidateEmail"], event["score"], "passed" if event["passed"] else "failed")
    print("full report:", event["reportUrl"])
if results["events"]:
    client.acknowledge_assessment_results([e["eventId"] for e in results["events"]])
```

`get_webhook_events` / `acknowledge_webhook_events` still work if you'd
rather handle both event types yourself in one poll — the link/result
methods above are just filtered, labeled wrappers around the same
Redis-backed queue.

## 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
